<?xml version="1.0" encoding="iso-8859-1"?>
<?xml-stylesheet href="../make-menu.xsl" type="text/xsl"?><html>
   <head>
      <this-is section="using-xquery" page="commandline" subpage=""/>
      <!--
           Generated at 2011-12-09T20:47:22.916Z--><title>Saxonica: XSLT and XQuery Processing: Running XQuery from the Command Line</title>
      <meta name="coverage" content="Worldwide"/>
      <meta name="copyright" content="Copyright Saxonica Ltd"/>
      <meta name="title"
            content="Saxonica: XSLT and XQuery Processing: Running XQuery from the Command Line"/>
      <meta name="robots" content="noindex,nofollow"/>
      <link rel="stylesheet" href="../saxondocs.css" type="text/css"/>
   </head>
   <body class="main">
      <h1>Running XQuery from the Command Line</h1>
      <p>A command is available to run a query contained in a file. The form of
command on the Java platform is:</p>
      <p class="command">java  net.sf.saxon.Query   [options]   -q:queryfile   [ <i>params...</i>]
</p>
      <p>On the .NET platform, the command is simply:</p>
      <p class="command">Query   [options]   -q:queryfile   [ <i>params...</i>]
</p>
      <p>The options must come first, then the params. If the last option before the params has
no leading hyphen and option letter then it is recognized as the -q option.</p>
      <p>The options are as follows (in any order). Square brackets indicate an optional value.</p>
      <table>
         <tr>
            <td content="para">
               <p>-backup:(on|off)</p>
            </td>
            <td content="para">
               <p>Only relevant when -update:on is specified. Default is on. When backup is enabled, any file that is updated
by the query will be preserved in its original state by renaming it, adding ".bak" to the original filename. If
backup is disabled, updated files will be silently overwritten.</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>-catalog:filenames</p>
            </td>
            <td content="para">
               <p><i>Filenames</i> is either a file name or a list of file names separated by semicolons;
               the files are OASIS XML catalogs used to define how public identifiers and system identifiers (URIs)
               used in a source document, query, or schema are to be redirected, typically to resources available
               locally. For more details see <a class="bodylink" href="../sourcedocs/xml-catalogs.xml">Using XML Catalogs</a>.
              </p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>-config:filename</p>
            </td>
            <td content="para">
               <p>Indicates that configuration information should be taken from the supplied
                        <a class="bodylink" href="../configuration/configuration-file.xml">configuration file</a>. Any options supplied
                        on the command line override options specified in the configuration file.
                </p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>-cr:classname</p>
            </td>
            <td content="para">
               <p>Use the specified CollectionURIResolver to process collection URIs passed to the
<code>collection()</code> function.
 The CollectionURIResolver is a user-defined class
that implements the <a class="bodylink" href="../javadoc/&gt;net/sf/saxon/lib/CollectionURIResolver.html"><code>CollectionURIResolver</code></a> interface.</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>-dtd:(on|off|recover)</p>
            </td>
            <td content="para">
               <p>Setting <code>-dtd:on</code> requests DTD-based validation of the source file and of any files read using the document()
function. Requires an XML parser that supports validation. The setting <code>-dtd:off</code> (which is the default)
suppresses DTD validation. The setting <code>-dtd:recover</code> performs DTD validation but treats the error as non-fatal if
it fails. Note that any external DTD is likely to be read even if not used for validation, because DTDs can contain
definitions of entities.</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>-expand:(on|off)</p>
            </td>
            <td content="para">
               <p>Normally, if validation using a DTD or Schema is requested, any fixed or default values defined
in the DTD or schema will be expanded. Specifying -expand:off suppresses this.  (In the case of DTD-defined defaults,
this might not work with all XML parsers. It does work with the Xerces parser (default for Java) and the 
Microsoft parser (default for .NET))</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>-explain[:filename]</p>
            </td>
            <td content="para">
               <p>Display a query execution plan. This is a representation of the
expression tree after rewriting by the optimizer. If no file name
is specified the output is sent to the standard error stream. The output is
a tree in XML format.</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>-ext:(on|off)</p>
            </td>
            <td content="para">
               <p>If <code>ext:off</code> is specified, suppress calls on dynamically-loaded external Java functions. 
This does not affect calls on integrated extension functions, including Saxon and EXSLT extension
functions. This option is useful when loading an untrusted query, perhaps from a remote
site using an <code>http://</code> URL; it ensures that the query cannot call arbitrary Java methods
and thereby gain privileged access to resources on your machine.
</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>-init:initializer</p>
            </td>
            <td content="para">
               <p>The value is the name of a user-supplied class
that implements the interface <a class="bodylink" href="../javadoc/net/sf/saxon/lib/Initializer.html"><code>Initializer</code></a>; this initializer will be called during the initialization process,
and may be used to set any options required on the Configuration programmatically. It is particularly useful for such tasks as
registering extension functions, collations, or external object models, especially in Saxon-HE where the option does not exist to
do this via a configuration file. </p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>-l[:(on|off)]</p>
            </td>
            <td content="para">
               <p>If <code>-l</code> or <code>-l:on</code> is specified, 
causes line and column numbers to be maintained for source documents. These are accessible
using the extension functions <code>saxon:line-number()</code> and <code>saxon:column-number()</code>. Line numbers are useful
when the purpose of the query is to find errors or anomalies in the source XML file.
Without this option, line numbers are available while source documents are being parsed
and validated, but they are not retained in the tree representation of the document.</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>-mr:classname</p>
            </td>
            <td content="para">
               <p>Use the specified ModuleURIResolver to process all query module URIs.
 The ModuleURIResolver is a user-defined class
that implements the <a class="bodylink" href="../javadoc/net/sf/saxon/lib/ModuleURIResolver.html"><code>ModuleURIResolver</code></a> interface.
 It is invoked to process URIs used in the <code>import module</code> declaration in the query prolog,
 and (if -u is also specified, or if the file name begins with "http:" or "file:") to process the URI
of the query source file provided on the command line.</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>-o:filename</p>
            </td>
            <td content="para">
               <p>Send output to named file. In the absence of this option, the results go to standard output.
The output format depends on whether the -wrap option is present.
The file is created if it does not already exist; any necessary directories will also be created.
If the file does exist, it is overwritten (even if the query fails).</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>-opt:0...10</p>
            </td>
            <td content="para">
               <p>Set optimization level. The value is
an integer in the range 0 (no optimization) to 10 (full optimization); currently all values other than 0 result in full
optimization but this is likely to change in future. The default is full optimization; this feature allows optimization
to be suppressed in cases where reducing compile time is important, or where optimization gets in the way of debugging,
or causes extension functions with side-effects to behave unpredictably. (Note however, that even with no optimization,
lazy evaluation may still cause the evaluation order to be not as expected.)
</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>-outval:(recover|fatal)</p>
            </td>
            <td content="para">
               <p>Normally, if validation of result documents is requested, a validation error is fatal. Setting
the option <code>-outval:recover</code> causes such validation failures to be treated as warnings. The validation
message is written both to the standard error stream, and (where possible) as a comment in the result
document itself.</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>-p[:(on|off)]</p>
            </td>
            <td content="para">
               <p>Use the PTreeURIResolver. This option is available in Saxon-EE only. It cannot be used in conjunction
with the -r option, and it automatically switches on the -u option. The effect is twofold. Firstly, Saxon-specific
file extensions are recognized in URIs (including the URI of the source document on the command line). Currently
the only Saxon-specific file extension is <code>.ptree</code>, which indicates that the source document is supplied
in the form of a Saxon PTree. This is a binary representation of an XML document, designed for speed of loading.
Secondly, Saxon-specific query parameters are recognized in a URI. Currently the only query parameter that is
recognized is <code>val</code>. This may take the values <code>strict</code>, <code>lax</code>, or <code>strip</code>.
For example, <code>source.xml?validation=strict</code> loads a document with strict schema validation.
</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>-pipe:(push|pull)</p>
            </td>
            <td content="para">
               <p>Execute query internally in push or pull mode. Default is push. This may give performance advantages for certain kinds of query,
especially queries that construct intermediate trees in memory. In practice when the output is serialized there is usually
little difference, and the option is there mainly for testing.
</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>-projection:(on|off)</p>
            </td>
            <td content="para">
               <p>Use (or don't use) document projection. Document Projection is a mechanism that analyzes a query to determine what parts of a document it
can potentially access, and then while building a tree to represent the document, leaves out those parts
of the tree that cannot make any difference to the result of the query. Requires Saxon-EE.
</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>-q:queryfile</p>
            </td>
            <td content="para">
               <p>Identifies the file containing the query. The file can be
specified as "-" to read the query from standard input. If this is the last option
then the "-q:" prefix may be omitted.</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>-qs:querystring</p>
            </td>
            <td content="para">
               <p>Allows the query to be specified
inline (if it contains spaces, you will need quotes
around the expression to keep the command line processor happy). 
For example <code>java net.sf.saxon.Query -qs:doc('a.xml')//p[1]</code> selects elements
within the file a.xml in the current directory.</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>-qversion:(1.0|3.0)</p>
            </td>
            <td content="para">
               <p>Specifies the XQuery language version supported. Default is "1.0". The value
"3.0" is currently only available with Saxon-EE. It supports a fairly small subset of the
features from the draft XQuery 3.0 specification (originally published as XQuery 1.1 but due to be renamed).</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>-r:classname</p>
            </td>
            <td content="para">
               <p>Use the specified URIResolver to process all URIs. The URIResolver is a user-defined class,
that implements the URIResolver interface defined in JAXP, whose function is to take a URI supplied as
a string, and return a SAX InputSource. It is invoked to process URIs used in the doc() function,
 and (if -u is also specified) to process the URI
of the source file provided on the command line.</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>-repeat:integer</p>
            </td>
            <td content="para">
               <p>Performs the transformation N times, where N is the specified integer. This option is useful for
performance measurement, since timings for the first few runs of the query are often dominated by Java warm-up time.</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>-s:filename-or-URI</p>
            </td>
            <td content="para">
               <p>Take input from the specified file. If the -u option is specified, or if the name begins with "file:"
or "http:", then the name is assumed to be a URI rather than a filename. This file must contain an
XML document. The document node of the document is made available to the query as the context item. 
The source document can be
specified as "-" to take the source from standard input. </p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>-sa</p>
            </td>
            <td content="para">
               <p>Invoke a schema-aware query. Requires Saxon-EE to be installed.</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>-strip:(all|none|ignorable)</p>
            </td>
            <td content="para">
               <p>Specifies what whitespace is to be stripped from source documents (applies both to the principal source
document and to any documents loaded for example using the <code>doc()</code> function. The default is
<code>none</code>: no whitespace stripping.</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>-t</p>
            </td>
            <td content="para">
               <p>Display version and timing information to the standard error output. The output also traces
the files that are read and written, and extension modules that are loaded.</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>-T[:classname]</p>
            </td>
            <td content="para">
               <p>Notify query tracing information. 
Also switches line numbering on for the source document. If a classname is
specified, it is a user-defined class, which must implement <a class="bodylink" href="../javadoc/net/sf/saxon/lib/TraceListener.html"><code>TraceListener</code></a>.
If the classname is omitted, a system-supplied trace listener is used. This traces execution of
function calls to the standard error output.</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>-TJ</p>
            </td>
            <td content="para">
               <p>Switches on tracing of the binding of calls to external Java methods.
This is useful when analyzing why Saxon fails to find a Java method to match
an extension function call in the stylesheet, or why it chooses one method over another when several
are available.</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>-traceout:filename</p>
            </td>
            <td content="para">
               <p>Indicates that the output of the <code>trace()</code> function should be directed to a specified file.
Alternatively, specify #out to direct the output to System.out, #err to send it to System.err (the default),
or #null to have it discarded. This option is ignored when a trace listener is in use: in that case, trace()
output goes to the registered trace listener.</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>-tree:(linked|tiny|tinyc)</p>
            </td>
            <td content="para">
               <p>Selects the implementation of the internal tree model. -tree:tiny selects the "tiny tree"
model (the default). -tree:linked selects the linked tree model.  -tree:tinyc selects the "condensed tiny tree" model.
See <a class="bodylink" href="../sourcedocs/choosingmodel.xml">Choosing a tree model</a>.</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>-u</p>
            </td>
            <td content="para">
               <p>Indicates that the name of the source document is a URI;
otherwise it is taken as a filename, unless it starts with "http:" or "file:", in which
case they it is taken as a URL.</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>-update:(on|off|discard)</p>
            </td>
            <td content="para">
               <p>Indicates whether XQuery Update syntax is accepted. This option requires Saxon-EE.
The value "on" enables XQuery update; any elegible files updated by the query are written back to filestore.
A file is eligible for updating if it was read using the <code>doc()</code> or <code>collection()</code> functions
using a URI that represents an updateable location. The context document supplied using the
<code>-s</code> option is <b>not</b> eligible for updating. 
The default value "off" disables update (any use of 
XQuery update syntax is an error). The value "discard" allows XQuery Update syntax, but modifications made to files are not saved in filestore.
If the document supplied in the -s option is updated, the updated document is serialized as the result of the query 
(writing it to the -o destination); updates to any other documents are simply discarded.Use of the <code>-t</code> option is recommended: it gives feedback on which files have been
updated by the query.</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>-val[:(strict|lax)]</p>
            </td>
            <td content="para">
               <p>Requests schema-based validation of the source file and of any files read using the doc()
function. This option is available only with Saxon-EE, and it automatically switches on the
-sa option. Specify <code>-val</code> or <code>-val:strict</code> to request strict validation,
or <code>-val:lax</code> for lax validation.</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>-wrap</p>
            </td>
            <td content="para">
               <p>Wraps the result sequence in an XML element structure that indicates the type of each node or
atomic value in the query result. This format can handle any type of query result. In the
absence of this option, the command effectively wraps a <code>document{}</code> constructor
around the supplied query, so that the result is a single XML document, which is then serialized.
This will fail if the query result includes constructs that cannot be added to a document node
in this way, notably free-standing attribute nodes.</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>-x:classname</p>
            </td>
            <td content="para">
               <p>Use specified SAX parser for source file and any files loaded using the document() function.
 The parser must be the fully-qualified class name
of a Java class that implements the org.xml.sax.Parser or org.xml.sax.XMLReader interface</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>-xi:(on|off)</p>
            </td>
            <td content="para">
               <p>Apply XInclude processing to all input XML documents (including schema documents as
well as source documents). This currently only works when documents are parsed using the Xerces
parser, which is the default in JDK 1.5 and later.</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>-xmlversion:(1.0|1.1)</p>
            </td>
            <td content="para">
               <p>If <code>-xmlversion:1.1</code> is specified, allows XML 1.1 and XML Namespaces 1.1 constructs. 
This option must be set if source documents 
using XML 1.1 are to be read, or if result documents are to be serialized as XML 1.1. This option
also enables use of XML 1.1 constructs within the stylesheet itself.</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>-xsd:file1;file2;file3...</p>
            </td>
            <td content="para">
               <p>Loads additional schema documents. The declarations in these schema documents are available when
validating source documents (or for use by the <code>validate{}</code> expression). This option may also be used
to supply the locations of schema documents that are imported into the query, in the case where the <code>import schema</code>
declaration gives the target namespace of the schema but not its location.</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>-xsdversion:(1.0|1.1)</p>
            </td>
            <td content="para">
               <p>If <code>-xsdversion:1.1</code> is specified, allows XML Schema 1.1 constructs such as assertions. 
This option must be set if schema documents 
using XML Schema 1.1 are to be read.</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>-xsiloc:(on|off)</p>
            </td>
            <td content="para">
               <p>If set to "on" (the default) the schema processor attempts to load any schema documents referenced
in <code>xsi:schemaLocation</code> and <code>xsi:noNamespaceSchemaLocation</code> attributes in the instance
document, unless a schema for the specified namespace (or non-namespace) is already available. If set to
"off", these attributes are ignored.</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>--<i>feature</i>:value</p>
            </td>
            <td content="para">
               <p>Set a feature defined in the <code>Configuration</code> interface. The names of features
are defined in <a class="bodylink" href="../configuration/config-features.xml">Configuration Features</a>: the value used here
is the part of the name after the last "/", for example <code>--allow-external-functions:off</code>.
Only features accepting a string or boolean may be set; for booleans the values true/false, on/off, yes/no, and 1/0
are recognized.</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>-?</p>
            </td>
            <td content="para">
               <p>Display command syntax</p>
            </td>
         </tr>
      </table>
      <p>A <i>param</i> takes the form <code>name=value</code>, <i>name</i> being the
name of the parameter, and <i>value</i> the value of the parameter. These parameters are
accessible within the query as external variables, using the <code>$name</code> syntax, provided
they are declared in the query prolog. If there is no such declaration, the supplied
 parameter value is silently ignored.</p>
      <p>A <i>param</i> preceded by a leading question mark (?) is interpreted as an XPath expression.
For example, <code>?time=current-dateTime()</code> sets the value of the external variable <code>$time</code>
to the value of the current date and time, as an instance of <code>xs:dateTime</code>, while 
<code>?debug=false()</code> sets the value of the variable <code>$debug</code> to the boolean value <code>false</code>.
If the parameter has a required type (for example <code>declare variable $p as xs:date external;</code>), then
the supplied value must be compatible with this type according to the standard rules for converting function arguments
(it doesn't need to satisfy the stricter rules that apply to variable initialization).
The static context for the XPath expression includes only the standard namespaces conventionally bound to the prefixes
<code>xs</code>, <code>fn</code>, <code>xsi</code>, and <code>saxon</code>. The static base URI (used when calling the
<code>doc()</code> function) is the current directory. The dynamic context contains no context item, position, or size,
and no variables.</p>
      <p>A <i>param</i> preceded by a leading plus sign (+) is interpreted as a filename or directory.
The content of the file is parsed as XML, and the resulting document node is passed to the stylesheet
as the value of the parameter. If the parameter value is a directory, then all the immediately contained
files are parsed as XML, and the resulting sequence of document nodes is passed as the value of the
parameter. For example, <code>+lookup=lookup.xml</code> sets the value of the external variable
<code>lookup</code> to the document node at the root of the tree representing the parsed contents
of the file <code>lookup.xml</code>.</p>
      <p>A <i>param</i> preceded by a leading exclamation mark (!) is interpreted as a serialization parameter.
For example, <code>!indent=yes</code> requests indented output, and <code>!encoding=iso-8859-1</code>
requests that the serialized output be in ISO 8859/1 encoding. This is equivalent to specifying
the option declaration <code>declare option saxon:output "indent=yes";</code> or 
<code>declare option saxon:output "encoding=iso-8859-1";</code>
in the query prolog.</p>
      <div class="boxed"
           style="border: solid thin; background-color: #B1CCC7; padding: 2px">If you are using the <code>bash</code> shell, you will need to escape "!" as "\!".</div>
      <p>Under Windows, and some other operating systems, it is possible to supply a value containing
spaces by enclosing it in double quotes, for example <code>name="John Smith"</code>. This is a feature
of the operating system shell, not something Saxon does, so it may not work the
same way under every operating system.</p>
      <p>If the parameter name is in a non-null namespace, the parameter can be given a value using
the syntax <code>{uri}localname=value</code>. Here <code>uri</code> is the namespace URI of the
parameter's name, and <code>localname</code> is the local part of the name.</p>
      <p>This applies also to output parameters. For example, you can set the indentation level to 4 by
using the parameter <code>!{http://saxon.sf.net/}indent-spaces=4</code>. In this case, however,
lexical QNames using the prefix "saxon" are also recognized, for example <code>!saxon:indent-spaces=4</code>.
 For the extended set of
output parameters supported by Saxon, see 
<a class="bodylink" href="../extensions/output-extras.xml">Additional serialization parameters</a>.</p>
      <table width="100%">
         <tr>
            <td>
               <p align="right"><a class="nav" href="api-query.xml">Next</a></p>
            </td>
         </tr>
      </table>
   </body>
</html>