1SAXON8Q(1) User Commands SAXON8Q(1)
2
6 saxon8q - manual page for saxon8q
7
9 saxon8q [options] query [ params...]
10
12 saxon8q runs a query contained in a file.
13
16 The options must come first, then the file name containing the query,
17 then the params.
18 The options are as follows (in any order):
20 -cr classname
22 Use the specified CollectionURIResolver to process collection
23 URIs passed to the collection() function. The CollectionURIRe‐
24 solver is a user-defined class that implements the
25 net.sf.saxon.CollectionURIResolver interface.
26 -ds Use the linked tree model for source documents. See Choosing a
28 Tree Model.
29 -dt Use the tinytree tree model for source documents. This is the
31 default tree model. See Choosing a Tree Model.
32 -e Display a query execution plan. This is a representation of the
34 expression tree after rewriting by the optimizer.
35 -l Causes line numbers to be maintained for source documents. These
37 are accessible using the extension function saxon:line-number().
38 Line numbers are useful when the purpose of the query is to find
39 errors or anomalies in the source XML file. Without this option,
40 line numbers are available while source documents are being
41 parsed and validated, but they are not retained in the tree rep‐
42 resentation of the document.
43 -mr classname
45 Use the specified ModuleURIResolver to process all query module
46 URIs. The ModuleURIResolver is a user-defined class that imple‐
47 ments the net.sf.saxon.query.ModuleURIResolver interface. It is
48 invoked to process URIs used in the import module declaration in
49 the query prolog, and (if -u is also specified, or if the file
50 name begins with http: or file:) to process the URI of the query
51 source file provided on the command line.
52 -noext Prevents the query calling external Java functions. This is use‐
54 ful for safety if the query is untrusted.
55 -o filename
57 Send output to named file. In the absence of this option, the
58 results go to standard output. The output format depends on
59 whether the -wrap option is present.
60 -p Use the PTreeURIResolver. This option is available in Saxon-SA
62 only. It cannot be used in conjunction with the -r option, and
63 it automatically switches on the -u and -sa options. The effect
64 is twofold. Firstly, Saxon-specific file extensions are recog‐
65 nized in URIs (including the URI of the source document on the
66 command line). Currently the only Saxon-specific file extension
67 is .ptree, which indicates that the source document is supplied
68 in the form of a Saxon PTree. This is a binary representation of
69 an XML document, designed for speed of loading. Secondly,
70 Saxon-specific query parameters are recognized in a URI. Cur‐
71 rently the only query parameter that is recognized is val. This
72 may take the values strict, lax, or strip. For example,
73 source.xml?validation=strict loads a document with strict schema
74 validation.
75 -pull Execute query in pull mode. This may give performance advantages
77 for certain kinds of query, especially queries that construct
78 intermediate trees in memory.
79 -r classname
81 Use the specified URIResolver to process all URIs. The URIRe‐
82 solver is a user-defined class, that implements the URIResolver
83 interface defined in JAXP, whose function is to take a URI sup‐
84 plied as a string, and return a SAX InputSource. It is invoked
85 to process URIs used in the doc() function, and (if -u is also
86 specified) to process the URI of the source file provided on the
87 command line.
88 -s filename-or-URI
90 Take input from the specified file. If the -u option is speci‐
91 fied, or if the name begins with file: or http:, then the name
92 is assumed to be a URI rather than a filename. This file must
93 contain an XML document. The document node of the document is
94 made available to the query as the context item. The source doc‐
95 ument can be specified as - to take the source from standard
96 input.
97 -sall Strips all whitespace text nodes from source documents before
99 any further processing, regardless of any xml:space attributes
100 in the source document.
101 -signorable
103 Strips all ignorable whitespace text nodes from source documents
104 before any further processing, regardless of any xml:space
105 attributes in the source document. Whitespace text nodes are
106 ignorable if they appear in elements defined in the DTD or
107 schema as having element-only content.
108 -snone Strips no whitespace before further processing.
110 -strip Equivalent to -sall: retained for compatibility.
112 -t Display version and timing information to the standard error
114 output. The output also traces the files that are read and writ‐
115 ten, and extension modules that are loaded.
116 -T Enable execution tracing. This will cause a trace of the query
118 execution to be output to the standard error output. The events
119 that are traced are currently function calls (entry and exit)
120 and element construction.
121 -TJ Switches on tracing of the binding of calls to external Java
123 methods. This is useful when analyzing why Saxon fails to find a
124 Java method to match an extension function call in the
125 stylesheet, or why it chooses one method over another when sev‐
126 eral are available.
127 -u Indicates that the name of the source document is a URI; other‐
129 wise it is taken as a filename, unless it starts with http: or
130 file:, in which case they it is taken as a URL.
131 -v Indicates that source documents are to be parsed using a vali‐
133 dating parser (this invokes DTD validation, not schema valida‐
134 tion).
135 -val This option is available only with Saxon-SA, and it automati‐
137 cally switches on the -sa option. It requests strict validation
138 of source documents using an XML Schema.
139 -vlax This option is available only with Saxon-SA, and it automati‐
141 cally switches on the -sa option. It requests lax validation of
142 source documents using an XML Schema. That is, the document will
143 be validated if a suitable schema is available, and will not be
144 validated otherwise.
145 -vw Indicates that validation errors found when validating the
147 result tree should be treated as warnings only. This option is
148 available only with the Saxon-SA version of the command,
149 com.saxonica.Query.
150 -wrap Wraps the result sequence in an XML element structure that indi‐
152 cates the type of each node or atomic value in the query result.
153 This format can handle any type of query result. In the absence
154 of this option, the command effectively wraps a document{} con‐
155 structor around the supplied query, so that the result is a sin‐
156 gle XML document, which is then serialized. This will fail if
157 the query result includes constructs that cannot be added to a
158 document node in this way, notably free-standing attribute
159 nodes.
160 -1.1 Allow XML 1.1 and XML Namespaces 1.1 constructs. This option
162 must be set if source documents using XML 1.1 are to be read, or
163 if result documents are to be serialized as XML 1.1. This option
164 also enables use of XML 1.1 constructs within the query itself.
165 -? Display command syntax
167 query Identifies the file containing the query. Mandatory. The argu‐
169 ment can be specified as - to read the query from standard input. The
170 query can also be specified inline by enclosing it in curly braces (if
171 it contains spaces, you will also need quotes outside the curly braces
172 to keep the command line processor happy). For example java
173 net.sf.saxon.Query {doc('a.xml')//p[1]} selects elements within the
174 file a.xml in the current directory.
175 A param takes the form name=value, name being the name of the
177 parameter, and value the value of the parameter. These parame‐
178 ters are accessible within the query as external variables,
179 using the syntax, provided they are declared in the query pro‐
180 log. If there is no such declaration, the supplied parameter
181 value is silently ignored.
182 A param preceded by a leading plus sign (+) is interpreted as a file‐
184 name or directory. The content of the file is parsed as XML, and the
185 resulting document node is passed to the stylesheet as the value of the
186 parameter. If the parameter value is a directory, then all the immedi‐
187 ately contained files are parsed as XML, and the resulting sequence of
188 document nodes is passed as the value of the parameter. For example,
189 +lookup=lookup.xml sets the value of the external variable lookup to
190 the document node at the root of the tree representing the parsed con‐
191 tents of the file lookup.xml.
192 A param preceded by a leading exclamation mark is interpreted as a
194 serialization parameter. For example, !indent=yes requests indented
195 output, and !encoding=iso-8859-1 requests that the serialized output be
196 in ISO 8859/1 encoding. This is equivalent to specifying the option
197 declaration declare option saxon:output indent=yes; or declare option
198 saxon:output encoding=iso-8859-1; in the query prolog.
199 Under Windows, and some other operating systems, it is possible to sup‐
201 ply a value containing spaces by enclosing it in double quotes, for
202 example name=John Smith. This is a feature of the operating system
203 shell, not something Saxon does, so it may not work the same way under
204 every operating system.
205 If the parameter name is in a non-null namespace, the parameter can be
207 given a value using the syntax {uri}localname=value. Here uri is the
208 namespace URI of the parameter's name, and localname is the local part
209 of the name.
210 This applies also to output parameters. For example, you can set the
212 indentation level to 4 by using the parameter
213 !{http://saxon.sf.net/}indent-spaces=4. For the extended set of output
214 parameters supported by Saxon, see Additional serialization parameters.
215
217 Michael H. Kay <mike@saxonica.com>
2188.7 March 2006 SAXON8Q(1)