SAXON8Q(1) User Commands SAXON8Q(1)NAME
saxon8q - manual page for saxon8q
SYNOPSIS
saxon8q [options] query [ params...]
DESCRIPTION
saxon8q runs a query contained in a file.
OPTIONS
The options must come first, then the file name containing the query,
then the params.
The options are as follows (in any order):
-cr classname
Use the specified CollectionURIResolver to process collection
URIs passed to the collection() function. The CollectionURIRe‐
solver is a user-defined class that implements the
net.sf.saxon.CollectionURIResolver interface.
-ds Use the linked tree model for source documents. See Choosing a
Tree Model.
-dt Use the tinytree tree model for source documents. This is the
default tree model. See Choosing a Tree Model.
-e Display a query execution plan. This is a representation of the
expression tree after rewriting by the optimizer.
-l Causes line numbers to be maintained for source documents. These
are accessible using the extension function saxon:line-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 rep‐
resentation of the document.
-mr classname
Use the specified ModuleURIResolver to process all query module
URIs. The ModuleURIResolver is a user-defined class that imple‐
ments 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.
-noext Prevents the query calling external Java functions. This is use‐
ful for safety if the query is untrusted.
-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.
-p 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 recog‐
nized 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. Cur‐
rently 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.
-pull Execute query in pull mode. This may give performance advantages
for certain kinds of query, especially queries that construct
intermediate trees in memory.
-r classname
Use the specified URIResolver to process all URIs. The URIRe‐
solver is a user-defined class, that implements the URIResolver
interface defined in JAXP, whose function is to take a URI sup‐
plied 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.
-s filename-or-URI
Take input from the specified file. If the -u option is speci‐
fied, 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 doc‐
ument can be specified as - to take the source from standard
input.
-sall Strips all whitespace text nodes from source documents before
any further processing, regardless of any xml:space attributes
in the source document.
-signorable
Strips all ignorable whitespace text nodes from source documents
before any further processing, regardless of any xml:space
attributes in the source document. Whitespace text nodes are
ignorable if they appear in elements defined in the DTD or
schema as having element-only content.
-snone Strips no whitespace before further processing.
-strip Equivalent to -sall: retained for compatibility.
-t Display version and timing information to the standard error
output. The output also traces the files that are read and writ‐
ten, and extension modules that are loaded.
-T Enable execution tracing. This will cause a trace of the query
execution to be output to the standard error output. The events
that are traced are currently function calls (entry and exit)
and element construction.
-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 sev‐
eral are available.
-u Indicates that the name of the source document is a URI; other‐
wise it is taken as a filename, unless it starts with http: or
file:, in which case they it is taken as a URL.
-v Indicates that source documents are to be parsed using a vali‐
dating parser (this invokes DTD validation, not schema valida‐
tion).
-val This option is available only with Saxon-SA, and it automati‐
cally switches on the -sa option. It requests strict validation
of source documents using an XML Schema.
-vlax This option is available only with Saxon-SA, and it automati‐
cally switches on the -sa option. It requests lax validation of
source documents using an XML Schema. That is, the document will
be validated if a suitable schema is available, and will not be
validated otherwise.
-vw Indicates that validation errors found when validating the
result tree should be treated as warnings only. This option is
available only with the Saxon-SA version of the command,
com.saxonica.Query.
-wrap Wraps the result sequence in an XML element structure that indi‐
cates 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{} con‐
structor around the supplied query, so that the result is a sin‐
gle 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.
-1.1 Allow 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 query itself.
-? Display command syntax
query Identifies the file containing the query. Mandatory. The argu‐
ment can be specified as - to read the query from standard input. The
query can also be specified inline by enclosing it in curly braces (if
it contains spaces, you will also need quotes outside the curly braces
to keep the command line processor happy). For example java
net.sf.saxon.Query {doc('a.xml')//p[1]} selects elements within the
file a.xml in the current directory.
A param takes the form name=value, name being the name of the
parameter, and value the value of the parameter. These parame‐
ters are accessible within the query as external variables,
using the syntax, provided they are declared in the query pro‐
log. If there is no such declaration, the supplied parameter
value is silently ignored.
A param preceded by a leading plus sign (+) is interpreted as a file‐
name 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 immedi‐
ately contained files are parsed as XML, and the resulting sequence of
document nodes is passed as the value of the parameter. For example,
+lookup=lookup.xml sets the value of the external variable lookup to
the document node at the root of the tree representing the parsed con‐
tents of the file lookup.xml.
A param preceded by a leading exclamation mark is interpreted as a
serialization parameter. For example, !indent=yes requests indented
output, and !encoding=iso-8859-1 requests that the serialized output be
in ISO 8859/1 encoding. This is equivalent to specifying the option
declaration declare option saxon:output indent=yes; or declare option
saxon:output encoding=iso-8859-1; in the query prolog.
Under Windows, and some other operating systems, it is possible to sup‐
ply a value containing spaces by enclosing it in double quotes, for
example name=John Smith. 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.
If the parameter name is in a non-null namespace, the parameter can be
given a value using the syntax {uri}localname=value. Here uri is the
namespace URI of the parameter's name, and localname is the local part
of the name.
This applies also to output parameters. For example, you can set the
indentation level to 4 by using the parameter
!{http://saxon.sf.net/}indent-spaces=4. For the extended set of output
parameters supported by Saxon, see Additional serialization parameters.
AUTHOR
Michael H. Kay <mike@saxonica.com>
8.7 March 2006 SAXON8Q(1)
