XQuery.exe

The XQSharp command line XQuery processor

The syntax to use XQuery.exe is as follows:

XQuery [options] query.xq [parameters]

In the above, query.xq should be replaced by the path to the query. The query can either be in textual XQuery format, or the XML XQueryX format (with the extension .xml or .xqx). Alternatively, replacing query.xq with a single "-" character indicates that the query should be read from the standard input stream. The [options] and [parameters] sections are optional and can be omitted.

Options

--compile
-c

Compiles and optimizes the query without running it. This can be useful to ensure a query is valid, without having a suitable input document at hand, and also for benchmarking purposes.

--dtd
-d

Enables the use of DTDs to validate input documents. By default, documents are not validated against their DTDs. Note that the DTDs are retrieved even when this option is disabled, as they are used to resolve entity references.

--emacs

Output errors and warnings in an single line format

--explain
-e

Displays the query execution plan. This is a representation of the query after it has been compiled and fully optimized. This explains how XQSharp intends to perform the query, and can be useful in highlighting errors in queries if they are producing unexpected results. The execution plan is output to the standard error stream.

--help
-?

Displays usage instructions for the command line tool.

--multiple
-m

Allows multiple compilation errors to be reported. By default, compilation is aborted after the first error is discovered.

--noserialize

Prevents the result of the query from being serialized and output. This is useful in combination with --time to measure the time taken to evaluate the query independent of the time taken to serialize the output.

-o file

Specifies a file to which the output of the query should be written. If the file already exists it is overwritten, otherwise a new file is created. If this option is omitted then the output of the query is sent to the standard output.

-O0

Disables compiler optimizations. This cannot be used in conjunction with any other -O? option.

-O1

Disables any compiler optimizations that significantly change the structure of the query. This is useful for producing an execution plan if the result of a query is not what you expect. This cannot be used in conjunction with any other -O? option.

-O2

Disables join optimizations. This feature is mainly for testing purposes. This cannot be used in conjunction with any other -O? option.

-O3

Enabled join optimizations. This is the default. This cannot be used in conjunction with any other -O? option.

-O4

Enables function specialization. This may significantly increase the compile time. This cannot be used in conjunction with any other -O? option.

--plan filename
-p filename

Write the execution plan as XML to the named file

--pedantic

Enables static type checking according exactly to the type checking rules as specified in the W3C XQuery Formal Semantics specification. In pedantic mode, XQSharp-specific extended type checking rules are not used. This cannot be used in conjunction with the --static option.

--preserve

Preserves all white space text nodes in all input documents. This cannot be used in conjunction with the -strip option.

--repeat n
-r n

Repeats compilation and evaluation of the query n times. This can be used in order to get more accurate timing measurements, since initialization can take a long time and dominate the first few runs. Note that this will also cause the result of the query to be serialized and output n times.

-s document

Sets the context document for the query. document can either be a path to, or the URI of, an XML document to use as the context item.

--schema
-v

Validates input documents with XML Schema against the available schemas. All documents passed in on the command line or read by the query are validated against the available schemas. The available schemas used for validation contain:

• Schemas imported using the --xsd option.
• Schemas imported in the query.
• Unless the --noxsiloc option is set, any schemas referenced in xs:schemaLocation or xs:noNamespaceSchemaLocation attributes are used to validate the document.

Note that this does not affect validate expressions, which will only validate against schemas imported in the query.

--static

Enables static type checking according to the type checking rules built into XQSharp. This ensures that any type errors that may be raised at run time are reported when the query is compiled. This cannot be used in conjunction with the --pedantic option.

--strip

Strips insignificant whitespace text nodes from all input documents. This cannot be used in conjunction with the -preserve option.

--time
-t

Displays the time taken to analyse and evaluate the query. Timing information is sent to the standard error stream. To get more accurate timings, this can be used in combination with the --repeats and --noserialize flags.

--trace

This option causes a message to be output to the console every time a document is accessed by the query, and enables output from the trace function in the query to be displayed. Trace information is sent to the standard error stream.

--unix
-u

Indicates that the output should use UNIX line endings (LF, a single "
" line feed character). By default, any new-line characters in the output document are replaced with a CRLF ("
").

--version

This option causes version information to be output to the console.

--xml10

Use XML 1.0 (5th edition) and Namespaces in XML 1.0. This prevents namespace undeclarations from being used within a query. Note that in the current version, only XML 1.0 4th edition documents can be used as inputs.

--xml11

Use XML 1.1 (2nd edition) and Namespaces in XML 1.1. This permits namespace undeclarations to be used within a query. Note that in the current version, only XML 1.0 4th editino documents can be used as inputs.

--xsd schema.xsd
-x schema.xsd

Adds a schema to the set of schemas available for validation. This mechanism also specifies the location of schemas imported in the query with no location hints. If the query imports a schema with the same namespace, then the schema su on the command line is used, regardless of which location hints are used.

--noxsiloc

Prevents schemas referenced by xsi:schemaLocation or xsi:noNamespaceSchemaLocation in imported documents from being loaded and added to the set of schemas used for validation.

Parameters

parametername=value
+parametername=value

Sets a query parameter.

A query parameter is the definition of a global variable declared as external in the query or an imported module. A query parameter can be set to either a value or a document. The syntax to set a parameter to a document is +parametername=document where document is a path or URI to an XML document. The syntax to set a parameter to a value is parametername=expression where expression is an expression which is evaluated to give the value of the parameter. In both cases, parametername is the local name of the parameter to be set. The parameter is assumed to have no namespace. An external variable declared with a namespace can be referred to with the syntax {namespace}localname. If no external variable is found with the right name, then this parameter is ignored.

!parameter=value

Sets a serialization parameter.

Serialization parameters define how the result of the query is serialized. This is equivalent to adding the following declarations to the query:

declare namespace serialization="http://www.xqsharp.com/serialization";
declare option serialization:parameter "value";

If the requested serialization parameter does not exist this parameter is ignored. If a parameter is also set in the query, then the value passed on the command line takes precedence.

For a detailed description of all the available serialization parameters, see Serialization parameters.

An example of using serialization parameters can be found in the Raytracer sample.