Running XQuery from the Command Line

-backup:(on|off)

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.

-cr:classname

Use the specified CollectionURIResolver to process collection URIs passed to the collection() function. The CollectionURIResolver is a user-defined class that implements the net.sf.saxon.CollectionURIResolver interface.

-dtd:(on|off)

Setting -dtd:on 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 -dtd:off (which is the default) suppresses DTD validation. Note that any external DTD is likely to be read even if not used for validation, because DTDs can contain definitions of entities.

-expand:(on|off)

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. (This might not work with all XML parsers)

-explain[:filename]

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.

-ext:(on|off)

If ext:off is specified, suppress calls on external Java functions, other than system-supplied Saxon and EXSLT extension functions. This option is useful when loading an untrusted stylesheet, perhaps from a remote site using an http:// URL; it ensures that the stylesheet cannot call Java methods and thereby gain privileged access to resources on your machine.

-l[:(on|off)]

If -l or -l:on is specified, causes line and column numbers to be maintained for source documents. These are accessible using the extension functions saxon:line-number() and saxon:column-number(). 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.

-mr:classname

Use the specified ModuleURIResolver to process all query module URIs. The ModuleURIResolver is a user-defined class that implements the net.sf.saxon.query.ModuleURIResolver interface. It is invoked to process URIs used in the import module 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.

-o:filename

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.

-outval:(recover|fatal)

Normally, if validation of result documents is requested, a validation error is fatal. Setting the option -outval:recover 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[:(on|off)]

Use the PTreeURIResolver. This option is available in Saxon-SA only. It cannot be used in conjunction with the -r option, and it automatically switches on the -u and -sa options. 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 .ptree, 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 val. This may take the values strict, lax, or strip. For example, source.xml?validation=strict loads a document with strict schema validation.

-pipe:push|pull

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.

-projection:(on|off)

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-SA.

-q:queryfile

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.

-qs:querystring

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 java net.sf.saxon.Query -qs:doc('a.xml')//p[1] selects elements within the file a.xml in the current directory.

-r:classname

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.

-repeat:integer

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.

-s:filename-or-URI

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.

-sa

Invoke a schema-aware transformation. Requires Saxon-SA to be installed.

-strip:(all|none|ignorable)

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 doc() function. The default is none: no whitespace stripping.

-t

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.

-T[:classname]

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 net.sf.saxon.trace.TraceListener. If the classname is omitted, a system-supplied trace listener is used. This traces execution of function calls to the standard error output.

-TJ

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.

-traceout:filename

Indicates that the output of the trace() 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.

-tree:[linked|tiny]

Selects the implementation of the internal tree model. -tree:tiny the "tiny tree" model (the default). -tree:linked selects the linked tree model. See Choosing a tree model.

-u

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.

-update:[on|off|discard]

Indicates whether XQuery Update syntax is accepted. This option requires Saxon-SA. The value "on" enables XQuery update; any files updated by the query are written back to filestore if they have a known document URI and that URI is an updateable location. 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.

-val[:(strict|lax)]

Requests schema-based validation of the source file and of any files read using the doc() function. This option is available only with Saxon-SA, and it automatically switches on the -sa option. Specify -val or -val:strict to request strict validation, or -val:lax for lax validation.

-wrap

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 document{} 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.

-x:classname

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

-xi

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.

-xmlversion:[1.0|1.1]

If -xmlversion:1.1 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.

-xsd:file1;file2;file3...

Loads additional schema documents. The declarations in these schema documents are available when validating source documents (or for use by the validate{} 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 import schema declaration gives the target namespace of the schema but not its location.

-xsdversion:[1.0|1.1]

If -xsdversion:1.1 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.

-xsiloc:on|off

If set to "on" (the default) the schema processor attempts to load any schema documents referenced in xsi:schemaLocation and xsi:noNamespaceSchemaLocation 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.

-?

Display command syntax

-ds | -dt

• -dt is equivalent to -tree:tiny

• -ds is equilvalent to -tree:linked

-e

Equivalent to -explain.

-noext

Equivalent to external:off

-novw

Equivalent to versionmsg:off

-sall

Equivalent to -strip:all

-signorable

Equivalent to -strip:ignorable

-snone

Equivalent to -strip:none

-TL classname

Equivalent to -T:classname

-TP

Equivalent to -T:net.sf.saxon.trace.TimedTraceListener

-v

Equivalent to -dtdval:on

-val

Equivalent to -val:strict

-vlax

Equivalent to -val:lax

-vw

Equivalent to -outval:recover

-1.1

Equivalent to -xmlversion:1.1

Next