Project

Profile

Help

How to connect?
Download (73.8 KB) Statistics
| Branch: | Revision:

he / src / userdoc / using-xquery.xml @ beaf15bc

1
<?xml version="1.0" encoding="utf-8"?> 
2
<article id="using-xquery" title="Using XQuery">
3
   <h1>Using XQuery</h1>
4

    
5

    
6
   <p>This section describes how to use Saxon as an XQuery processor, either from the command line,
7
      or from the Java API.</p>
8

    
9
   <p>For details of the .NET API, see <a class="bodylink" href="/dotnet/dotnetapi">Saxon API for
10
         .NET</a>.</p>
11

    
12
   <p>Saxon 9.8 and later releases implement the <a href="https://www.w3.org/TR/xquery-31/" class="bodylink">XQuery 3.1 Recommendation</a> 
13
      dated 18 April 2017. Because XQuery 3.1 is backwards compatible with XQuery 1.0 and XQuery 3.0, Saxon will
14
      also execute queries written according to the 1.0 or 3.0 versions of the specification. Saxon no longer
15
      has a mode to execute as an XQuery 1.0 or 3.0 processor (that is, to reject constructs 
16
      that were not present in earlier versions of the language). For information about the conformance of Saxon to the XQuery 3.1
17
      specification, and about the handling of implementation-defined features of the
18
      specification, see <a class="bodylink" href="/conformance">Conformance</a>.</p>
19

    
20
   <p>Saxon uses the same run-time engine to support both XQuery and XSLT, reflecting the fact that
21
      the two languages have very similar semantics. Most of the compile-time code (in particular,
22
      the type checking logic and the optimizer) is also common. The XQuery support in Saxon
23
      consists essentially of an XQuery parser (which is itself an extension of the XPath parser);
24
      the parser generates the same internal interpretable code as the XSLT processor. There are
25
      also some constructs in the internal expression tree that will only be generated from XQuery
26
      source rather than XSLT source; examples are the XQuery <code>order by</code> and <code>group
27
         by</code> clauses, which have no direct XSLT equivalent.</p>
28

    
29
   <p>The XQuery processor may be invoked either from the operating system command line, or via an
30
      API from a user-written application. There is no graphical user interface provided.</p>
31

    
32
   <p>Saxon is an in-memory processor. Unless you can take advantage of <a class="bodylink"
33
         href="/sourcedocs/streaming">streaming</a>, Saxon is designed to process source documents
34
      that fit in memory. Saxon has been used successfully to process source documents of 100Mbytes
35
      or more without streaming, but if you attempt anything this large, you need to be aware (a)
36
      that you will need to allocate sufficient memory to the Java VM (at least 5 times the size of
37
      the source document), and (b) that complex FLWOR expressions may be very time-consuming to
38
      execute. (In this scenario, Saxon-EE is recommended, because it has a more powerful optimizer
39
      for complex joins.)</p>
40

    
41
   <aside>The memory available in the Java heap is controlled using the <code>-Xmx</code> option on
42
      the command line, for example <code>java -Xmx1024m net.sf.saxon.Query ...</code> allocates
43
      1Gb.</aside>
44

    
45
   <p>
46
      <i>For details of how to set up collation URIs for use in XQuery, see <a class="bodylink"
47
            href="/extensibility/config-extend/collation">Collations</a>.</i>
48
   </p>
49
   <section id="commandline" title="Running XQuery from the Command Line">
50
      <h1>Running XQuery from the Command Line</h1>
51

    
52

    
53
      <p>A command is available to run a query contained in a file. The form of command on the Java
54
         platform is:</p>
55
      <kbd>java  net.sf.saxon.Query   [options]  [ <i>params...</i>] </kbd>
56

    
57
      <p>On the .NET platform, the command is simply:</p>
58
      <kbd>Query   [options]  [ <i>params...</i>] </kbd>
59

    
60
      <p>The options will generally include either <code>-q:queryFile</code> which takes the query from a file,
61
      or <code>-qs:query</code> in which the query appears directly in the command line (usually in quotes).</p>
62
      
63
      <p>The options must come first, then the parameters. If the last option before the parameters
64
         has no leading hyphen and option letter then it is recognized as the <code>-q</code>
65
         option.</p>
66

    
67
      <h2 class="subtitle">Command line options</h2>
68

    
69
      <p>The options are as follows (in any order). Square brackets indicate an optional value.</p>
70
      <table>
71
         <tr>
72
            <td>
73
               <p>-backup:(on|off)</p>
74
            </td>
75
            <td>
76
               <p>Only relevant when <code>-update:on</code> is specified. Default is
77
                     <code>on</code>. When backup is enabled, any file that is updated by the query
78
                  will be preserved in its original state by renaming it, adding ".bak" to the
79
                  original filename. If backup is disabled, updated files will be silently
80
                  overwritten.</p>
81
            </td>
82
         </tr>
83
         <tr>
84
            <td>
85
               <p>-catalog:filenames</p>
86
            </td>
87
            <td>
88
               <p><i>filenames</i> is either a file name or a list of file names separated by
89
                  semicolons; the files are OASIS XML catalogs used to define how public identifiers
90
                  and system identifiers (URIs) used in a source document, query, or schema are to
91
                  be redirected, typically to resources available locally. For more details see <a
92
                     class="bodylink" href="/sourcedocs/xml-catalogs">Using XML catalogs</a>. </p>
93
            </td>
94
         </tr>
95
         <tr>
96
            <td>
97
               <p>-config:filename</p>
98
            </td>
99
            <td>
100
               <p>Indicates that configuration information should be taken from the supplied <a
101
                     class="bodylink" href="/configuration/configuration-file">configuration
102
                     file</a>. Any options supplied on the command line override options specified
103
                  in the configuration file. </p>
104
            </td>
105
         </tr>
106
         <tr>
107
            <td>
108
               <p>-dtd:(on|off|recover)</p>
109
            </td>
110
            <td>
111
               <p>Setting <code>-dtd:on</code> requests DTD-based validation of the source file and
112
                  of any files read using the <code>doc()</code> function. Requires an XML
113
                  parser that supports validation. The setting <code>-dtd:off</code> (which is the
114
                  default) suppresses DTD validation. The setting <code>-dtd:recover</code> performs
115
                  DTD validation but treats the error as non-fatal if it fails. Note that any
116
                  external DTD is likely to be read even if not used for validation, because DTDs
117
                  can contain definitions of entities.</p>
118
            </td>
119
         </tr>
120
         <tr>
121
            <td>
122
               <p>-expand:(on|off)</p>
123
            </td>
124
            <td>
125
               <p>Normally, if validation using a DTD or schema is requested, any fixed or default
126
                  values defined in the DTD or schema will be expanded. Specifying
127
                     <code>-expand:off</code> suppresses this. (In the case of DTD-defined defaults,
128
                  this might not work with all XML parsers. It does work with the Xerces parser
129
                  (default for Java) and the Microsoft parser (default for .NET).)</p>
130
            </td>
131
         </tr>
132
         <tr>
133
            <td>
134
               <p>-explain[:filename]</p>
135
            </td>
136
            <td>
137
               <p>Display a query execution plan. This is a representation of the expression tree
138
                  after rewriting by the optimizer. If no file name is specified the output is sent
139
                  to the standard error stream. The output is a tree in XML format.</p>
140
            </td>
141
         </tr>
142
         <tr>
143
            <td>
144
               <p>-ext:(on|off)</p>
145
            </td>
146
            <td>
147
               <p>If <code>ext:off</code> is specified, suppress calls on dynamically-loaded
148
                  external Java functions. This does not affect calls on integrated extension
149
                  functions, including Saxon and EXSLT extension functions. This option is useful
150
                  when loading an untrusted query, perhaps from a remote site using an
151
                     <code>http://</code> URL; it ensures that the query cannot call arbitrary Java
152
                  methods and thereby gain privileged access to resources on your machine. </p>
153
            </td>
154
         </tr>
155
         <tr>
156
            <td>
157
               <p>-init:initializer</p>
158
            </td>
159
            <td>
160
               <p>The value is the name of a user-supplied class that implements the interface <a
161
                     class="javalink" href="net.sf.saxon.lib.Initializer">Initializer</a>; this
162
                  initializer will be called during the initialization process, and may be used to
163
                  set any options required on the <code>Configuration</code> programmatically.</p>
164
            </td>
165
         </tr>
166
         <tr>
167
            <td>
168
               <p>-l[:(on|off)]</p>
169
            </td>
170
            <td>
171
               <p>If <code>-l</code> or <code>-l:on</code> is specified, causes line and column
172
                  numbers to be maintained for source documents. These are accessible using the
173
                  extension functions <code>saxon:line-number()</code> and
174
                     <code>saxon:column-number()</code>. Line numbers are useful when the purpose of
175
                  the query is to find errors or anomalies in the source XML file. Without this
176
                  option, line numbers are available while source documents are being parsed and
177
                  validated, but they are not retained in the tree representation of the
178
                  document.</p>
179
            </td>
180
         </tr>
181
         <tr>
182
            <td>
183
               <p>-mr:classname</p>
184
            </td>
185
            <td>
186
               <p>Use the specified <code>ModuleURIResolver</code> to process all query module URIs.
187
                  The <code>ModuleURIResolver</code> is a user-defined class that implements the <a
188
                     class="javalink" href="net.sf.saxon.lib.ModuleURIResolver"
189
                     >ModuleURIResolver</a> interface. It is invoked to process URIs used in the
190
                     <code>import module</code> declaration in the query prolog, and (if
191
                     <code>-u</code> is also specified, or if the file name begins with
192
                     <code>http:</code>, <code>https:</code>, <code>file:</code> or
193
                     <code>classpath:</code>) to process the URI of the query source file provided
194
                  on the command line.</p>
195
            </td>
196
         </tr>
197
         <tr>
198
            <td>
199
               <p>-now:yyyy-mm-ddThh:mm:ss+hh:mm</p>
200
            </td>
201
            <td>
202
               <p>Sets the value of <code>current-dateTime()</code> (and
203
                  <code>implicit-timezone()</code>) for the query. This is designed for
204
                  testing, to enable repeatable results to be obtained for comparison with reference
205
                  results, or to test that queries can handle significant dates and times such
206
                  as end-of-year processing.</p>
207
            </td>
208
         </tr>
209
         <tr>
210
            <td>
211
               <p>-o:filename</p>
212
            </td>
213
            <td>
214
               <p>Send output to named file. In the absence of this option, the results go to
215
                  standard output. The output format depends on whether the <code>-wrap</code>
216
                  option is present. The file is created if it does not already exist; any necessary
217
                  directories will also be created. If the file does exist, it is overwritten (even
218
                  if the query fails).</p>
219
            </td>
220
         </tr>
221
         <tr>
222
            <td>
223
               <p>-opt:[-]flags</p>
224
            </td>
225
            <td>
226
               <p>Allows individual optimizations to be enabled or disabled selectively. There is a
227
                  set of single-letter flags identifying particular optimizations:</p>
228
               <ul>
229
                  <li>c: generate bytecode</li>
230
                  <li>d: detect void path expressions</li>
231
                  <li>e: cache regular expressions</li>
232
                  <li>f: inline functions</li>
233
                  <li>g: extract global variables</li>
234
                  <li>j: just-in-time compilation of template rules (currently XSLT-only)</li>
235
                  <li>k: create keys</li>
236
                  <li>l: loop lifting</li>
237
                  <li>m: miscellaneous</li>
238
                  <li>n: constant folding</li>
239
                  <li>r: template rule-sets (not relevant to XQuery)</li>
240
                  <li>s: extract common subexpressions</li>
241
                  <li>t: tail call optimization</li>
242
                  <li>v: inline variables</li>
243
                  <li>w: create switch statements</li>
244
                  <li>x: index predicates</li>
245
               </ul>
246
               <p>A value such as <code>opt:gs</code> runs with only the selected optimizations;
247
                  <code>opt:-gs</code> runs with the selected optimizations disabled and all others
248
                  enabled. The value <code>opt:0</code> suppresses all optimizations. The default is full
249
                  optimization; this feature allows optimization to be suppressed in cases where
250
                  reducing compile time is important, or where optimization gets in the way of
251
                  debugging, or causes extension functions with side-effects to behave
252
                  unpredictably. (Note however, that even with no optimization, lazy evaluation may
253
                  still cause the evaluation order to be not as expected.) </p>
254
            </td>
255
         </tr>
256
         <tr>
257
            <td>
258
               <p>-outval:(recover|fatal)</p>
259
            </td>
260
            <td>
261
               <p>Normally, if validation of result documents is requested, a validation error is
262
                  fatal. Setting the option <code>-outval:recover</code> causes such validation
263
                  failures to be treated as warnings. The validation message is written both to the
264
                  standard error stream, and (where possible) as a comment in the result document
265
                  itself.</p>
266
            </td>
267
         </tr>
268
         <tr>
269
            <td>
270
               <p>-p[:(on|off)]</p>
271
            </td>
272
            <td>
273
              <p>Enable recognition of query parameters (such as <code>xinclude=yes</code>)
274
                in the <code>StandardURIResolver</code>. This option is available in Saxon-PE and Saxon-EE only.
275
                It cannot be used in conjunction with the <code>-r</code> option, and it
276
                automatically switches on the <code>-u</code> and <code>-sa</code> options. The
277
                effect is that Saxon-specific query parameters are recognized in a URI. One query
278
                parameter that is recognized is <code>validation</code>. This may take the values
279
                <code>strict</code>, <code>lax</code>, or <code>strip</code>. For example,
280
                <code>source.xml?validation=strict</code> loads a document with strict schema
281
                validation. </p>
282
            </td>
283
         </tr>
284
         <tr>
285
            <td>
286
               <p>-projection:(on|off)</p>
287
            </td>
288
            <td>
289
               <p>Use (or don't use) document projection. <a href="/sourcedocs/projection">Document
290
                     Projection</a> is a mechanism that analyzes a query to determine what parts of
291
                  a document it can potentially access, and then while building a tree to represent
292
                  the document, leaves out those parts of the tree that cannot make any difference
293
                  to the result of the query. Requires Saxon-EE. </p>
294
            </td>
295
         </tr>
296
         <tr>
297
            <td>
298
               <p>-q:queryfile</p>
299
            </td>
300
            <td>
301
               <p>Identifies the file containing the query. If this is the last option then the
302
                  <code>-q:</code> prefix may be omitted. The file can be specified as "-" to read
303
                  the query from standard input: in this case the base URI is that of the current directory.</p>
304
            </td>
305
         </tr>
306
         <tr>
307
            <td>
308
               <p>-qs:querystring</p>
309
            </td>
310
            <td>
311
               <p>Allows the query to be specified inline (if it contains spaces, you will need
312
                  quotes around the expression to keep the command line processor happy). The static base
313
                  URI of the query is taken from the current working directory. So, for
314
                  example, <code>java net.sf.saxon.Query -qs:doc('a.xml')//p[1]</code> selects
315
                  elements within the file <code>a.xml</code> in the current directory.</p>
316
            </td>
317
         </tr>
318
         <tr>
319
            <td>
320
               <p>-quit:(on|off)</p>
321
            </td>
322
            <td>
323
               <p>With the default setting, <code>on</code>, the command will quit the Java VM and
324
                  return an exit code if a failure occurs. This is useful when running from an
325
                  operating system shell. With the setting <code>quit:off</code> the command instead
326
                  throws a <code>RunTimeException</code>, which is more useful when the command is
327
                  invoked from another Java application such as Ant. </p>
328
            </td>
329
         </tr>
330
         <tr>
331
            <td>
332
               <p>-r:classname</p>
333
            </td>
334
            <td>
335
               <p>Use the specified <code>URIResolver</code> to process all URIs. The
336
                     <code>URIResolver</code> is a user-defined class, that implements the
337
                     <code>URIResolver</code> interface defined in JAXP, whose function is to take a
338
                  URI supplied as a string, and return a SAX <code>InputSource</code>. It is invoked
339
                  to process URIs used in the <code>doc()</code> function, and (if <code>-u</code>
340
                  is also specified) to process the URI of the source file provided on the command
341
                  line.</p>
342
            </td>
343
         </tr>
344
         <tr>
345
            <td>
346
               <p>-repeat:integer</p>
347
            </td>
348
            <td>
349
               <p>Performs the transformation N times, where N is the specified integer. This option
350
                  is useful for performance measurement, since timings for the first few runs of the
351
                  query are often dominated by Java warm-up time.</p>
352
            </td>
353
         </tr>
354
         <tr>
355
            <td>
356
               <p>-s:filename-or-URI</p>
357
            </td>
358
            <td>
359
               <p>Take input from the specified file. If the <code>-u</code> option is specified, or
360
                  if the name begins with "file:" or "http:", then the name is assumed to be a URI
361
                  rather than a filename. This file must contain an XML document. The document node
362
                  of the document is made available to the query as the context item. The filename can be specified as "-" to read
363
                  the source document from standard input: in this case the base URI is that of the current directory. </p>
364
            </td>
365
         </tr>
366
         <tr>
367
            <td>
368
               <p>-sa</p>
369
            </td>
370
            <td>
371
               <p>Invoke a schema-aware query. Requires Saxon-EE to be installed.</p>
372
            </td>
373
         </tr>
374
         <tr>
375
            <td>
376
               <p>-scmin:filename</p>
377
            </td>
378
            <td>
379
               <p>Loads a precompiled schema component model from the given file. The file should be
380
                  generated in a previous run using the <code>-export</code> option. When this
381
                  option is used, the <code>-xsd</code> option should not be present. Schemas loaded
382
                  from an SCM file are assumed to be valid, without checking.</p>
383
               <p><i>This option is retained for compatibility. From Saxon 9.7, SCM files can also be
384
                  supplied in the <code>-xsd</code> option.</i></p>
385
            </td>
386
         </tr>
387
         <tr>
388
            <td>
389
               <p>-stream:(on|off)</p>
390
            </td>
391
            <td>
392
               <p>Use (or don't use) streaming. Streaming allows simple queries to be executed while
393
                  the source document is being read, avoiding the need to build a tree
394
                  representation of the document in memory. For information about the kind of
395
                  queries that can be streamed, see <a href="/sourcedocs/streaming/streamed-query"
396
                     >Streaming XQuery</a>. If the query cannot be streamed, execution will fail
397
                  with diagnostic errors. Requires Saxon-EE. </p>
398
            </td>
399
         </tr>
400
         <tr>
401
            <td>
402
               <p>-strip:(all|none|ignorable)</p>
403
            </td>
404
            <td>
405
               <p>Specifies what whitespace is to be stripped from source documents (applies both to
406
                  the principal source document and to any documents loaded for example using the
407
                     <code>doc()</code> function). The default is <code>none</code>: no whitespace
408
                  stripping.</p>
409
            </td>
410
         </tr>
411
         <tr>
412
            <td>
413
               <p>-t</p>
414
            </td>
415
            <td>
416
               <p>Display version and timing information to the standard error output. The output
417
                  also traces the files that are read and written, and extension modules that are
418
                  loaded.</p>
419
            </td>
420
         </tr>
421
         <tr>
422
            <td>
423
               <p>-T[:classname]</p>
424
            </td>
425
            <td>
426
               <p>Notify query tracing information. Also switches line numbering on for the source
427
                  document. If a classname is specified, it is a user-defined class, which must
428
                  implement <a class="javalink" href="net.sf.saxon.lib.TraceListener"
429
                     >TraceListener</a>. If the classname is omitted, a system-supplied trace
430
                  listener is used. This traces execution of function calls to the standard error
431
                  output. For performance profiling, set
432
                  classname to <code>net.sf.saxon.trace.TimingTraceListener</code>. This creates an
433
                  output file giving timings for each instruction executed. This output file can
434
                  subsequently be analyzed to give an execution time profile for the query. See
435
                  <a class="bodylink" href="../performanceanalysis">Performance Analysis</a>.</p>
436
            </td>
437
         </tr>
438
         <tr>
439
            <td>
440
               <p>-TB:filename</p>
441
            </td>
442
            <td>
443
               <p>Monitors generation of hot-spot bytecode and produces an XML report on the given
444
                  filename giving, for each expression that was a candidate for bytecode generation
445
                  and that was actually executed, data about the number of times and speed of execution
446
                  in the interpreter, the number of times and speed of execution in compiled form,
447
                  and the cost of compilation. Note that if an expression A contains an expression B
448
                  and both are candidates for bytecode generation, then the statistics for B relate only
449
                  to the time before A was compiled in its own right.</p>
450
            </td>
451
         </tr>
452
         <tr>
453
            <td>
454
               <p>-TJ</p>
455
            </td>
456
            <td>
457
               <p>Switches on tracing of the binding of calls to external Java methods. This is
458
                  useful when analyzing why Saxon fails to find a Java method to match an extension
459
                  function call in the query, or why it chooses one method over another when
460
                  several are available.</p>
461
            </td>
462
         </tr>
463
         <tr>
464
            <td>
465
               <p>-Tlevel:none|low|normal|high</p>
466
            </td>
467
            <td>
468
               <p>Controls the level of detail of the tracing produced by the <code>-T</code> option. The values are:</p>
469
               <ul>
470
                  <li><code>none</code> effectively switches tracing off. </li>
471
                  <li><code>low</code> traces function calls.</li>
472
                  <li><code>normal</code> traces execution of significant expressions such as element constructors.</li>
473
                  <li><code>high</code> traces execution of finer-grained expressions such as the clauses of a FLWOR expression.</li>
474
                  </ul>
475
                 
476
            </td>
477
         </tr>
478
         <tr>
479
            <td>
480
               <p>-Tout:filename</p>
481
            </td>
482
            <td>
483
               <p>Directs the output of tracing to a specified file (assuming that <code>-T</code> is enabled).</p>
484
            </td>
485
         </tr>
486
         <tr>
487
            <td>
488
               <p>-TP:filename</p>
489
            </td>
490
            <td>
491
               <p>This is equivalent to setting
492
                  <code>-T:net.sf.saxon.trace.TimedTraceListener</code> and
493
                  <code>-traceout:filename</code>; that is, it causes trace profile information
494
                  to be set to the specified file. This output file can subsequently be analyzed to
495
                  give an execution time profile for the query. See <a class="bodylink"
496
                     href="../performanceanalysis">Performance Analysis</a>.</p>
497
            </td>
498
         </tr>
499
         <tr>
500
            <td>
501
               <p>-traceout:filename</p>
502
            </td>
503
            <td>
504
               <p>Indicates that the output of the <code>trace()</code> function should be directed
505
                  to a specified file. Alternatively, specify <code>#out</code> to direct the output
506
                  to <code>System.out</code>, <code>#err</code> to send it to
507
                     <code>System.err</code> (the default), or <code>#null</code> to have it
508
                  discarded. This option is ignored when a trace listener is in use: in that case,
509
                     <code>trace()</code> output goes to the registered trace listener.</p>
510
            </td>
511
         </tr>
512
         <tr>
513
            <td>
514
               <p>-tree:(linked|tiny|tinyc)</p>
515
            </td>
516
            <td>
517
               <p>Selects the implementation of the internal tree model. <code>tiny</code> selects
518
                  the "tiny tree" model (the default), <code>linked</code> selects the linked tree
519
                  model, <code>tinyc</code> selects the "condensed tiny tree" model. See <a
520
                     class="bodylink" href="/sourcedocs/choosingmodel">Choosing a tree
521
                  model</a>.</p>
522
            </td>
523
         </tr>
524
         <tr>
525
            <td>
526
               <p>-u</p>
527
            </td>
528
            <td>
529
               <p>Indicates that the name of the source document is a URI; otherwise it is taken as
530
                  a filename, unless it starts with <code>http:</code>, <code>https:</code>,
531
                     <code>file:</code> or <code>classpath:</code>, in which case it is taken as a
532
                  URL.</p>
533
            </td>
534
         </tr>
535
         <tr>
536
            <td>
537
               <p>-update:(on|off|discard)</p>
538
            </td>
539
            <td>
540
               <p>Indicates whether XQuery Update syntax is accepted. This option requires Saxon-EE.
541
                  The value <code>on</code> enables XQuery update; any eligible files updated by the
542
                  query are written back to filestore. A file is eligible for updating if it was
543
                  read using the <code>doc()</code> or <code>collection()</code> functions using a
544
                  URI that represents an updateable location. The context document supplied using
545
                  the <code>-s</code> option is <strong>not</strong> eligible for updating. The
546
                  default value <code>off</code> disables update (any use of XQuery update syntax is
547
                  an error). The value <code>discard</code> allows XQuery Update syntax, but
548
                  modifications made to files are not saved in filestore. If the document supplied
549
                  in the <code>-s</code> option is updated, the updated document is serialized as
550
                  the result of the query (writing it to the <code>-o</code> destination); updates
551
                  to any other documents are simply discarded. Use of the <code>-t</code> option is
552
                  recommended: it gives feedback on which files have been updated by the query.</p>
553
            </td>
554
         </tr>
555
         <tr>
556
            <td>
557
               <p>-val[:(strict|lax)]</p>
558
            </td>
559
            <td>
560
               <p>Requests schema-based validation of the source file and of any files read using
561
                  the <code>doc()</code> function. This option is available only with Saxon-EE, and
562
                  it automatically switches on the <code>-sa</code> option. Specify
563
                     <code>-val</code> or <code>-val:strict</code> to request strict validation, or
564
                     <code>-val:lax</code> for lax validation.</p>
565
            </td>
566
         </tr>
567
         <tr>
568
            <td>
569
               <p>-wrap</p>
570
            </td>
571
            <td>
572
               <p>Wraps the result sequence in an XML element structure that indicates the type of
573
                  each node or atomic value in the query result. This format can handle any type of
574
                  query result. In the absence of this option, the command effectively wraps a
575
                     <code>document{}</code> constructor around the supplied query, so that the
576
                  result is a single XML document, which is then serialized. This will fail if the
577
                  query result includes constructs that cannot be added to a document node in this
578
                  way, notably free-standing attribute nodes.</p>
579
            </td>
580
         </tr>
581
         <tr>
582
            <td>
583
               <p>-x:classname</p>
584
            </td>
585
            <td>
586
               <p>Use the specified SAX parser for the source file and any files loaded using the
587
                     <code>doc()</code> function. The parser must be the fully-qualified class
588
                  name of a Java class that implements the <code>org.xml.sax.XMLReader</code> or
589
                     <code>javax.xml.parsers.SAXParserFactory</code> interface, and it must be
590
                  instantiable using a zero-argument public constructor.</p>
591
            </td>
592
         </tr>
593
         <tr>
594
            <td>
595
               <p>-xi:(on|off)</p>
596
            </td>
597
            <td>
598
               <p>Apply XInclude processing to all source XML documents (but not to schema documents). 
599
                  This currently only works when documents are parsed
600
                  using the Xerces parser, which is the default in JDK 1.5 and later.</p>
601
            </td>
602
         </tr>
603
         <tr>
604
            <td>
605
               <p>-xmlversion:(1.0|1.1)</p>
606
            </td>
607
            <td>
608
               <p>If <code>-xmlversion:1.1</code> is specified, allows XML 1.1 and XML Namespaces
609
                  1.1 constructs. This option must be set if source documents using XML 1.1 are to
610
                  be read, or if result documents are to be serialized as XML 1.1. This option also
611
                  enables use of XML 1.1 constructs within the query itself.</p>
612
            </td>
613
         </tr>
614
         <tr>
615
            <td>
616
               <p>-xsd:file1;file2;file3...</p>
617
            </td>
618
            <td>
619
               <p>Loads additional schema documents. The declarations in these schema documents are
620
                  available when validating source documents (or for use by the
621
                     <code>validate{}</code> expression). This option may also be used to supply the
622
                  locations of schema documents that are imported into the query, in the case where
623
                  the <code>import schema</code> declaration gives the target namespace of the
624
                  schema but not its location.</p>
625
            </td>
626
         </tr>
627
         <tr>
628
            <td>
629
               <p>-xsdversion:(1.0|1.1)</p>
630
            </td>
631
            <td>
632
               <p>If <code>-xsdversion:1.1</code> is specified (the default), allows schema
633
                  documents using XML Schema 1.1 to be read, and XML Schema 1.1 constructs
634
                  such as assertions.</p>
635
            </td>
636
         </tr>
637
         <tr>
638
            <td>
639
               <p>-xsiloc:(on|off)</p>
640
            </td>
641
            <td>
642
               <p>If set to <code>on</code> (the default) the schema processor attempts to load any
643
                  schema documents referenced in <code>xsi:schemaLocation</code> and
644
                     <code>xsi:noNamespaceSchemaLocation</code> attributes in the instance document,
645
                  unless a schema for the specified namespace (or non-namespace) is already
646
                  available. If set to <code>off</code>, these attributes are ignored.</p>
647
            </td>
648
         </tr>
649
         <tr>
650
            <td>
651
               <p>--<i>feature</i>:value</p>
652
            </td>
653
            <td>
654
               <p>Set a feature defined in the <code>Configuration</code> interface. The names of
655
                  features are defined in the Javadoc for class <a class="javalink"
656
                     href="net.sf.saxon.lib.Feature">Feature</a> (alternatively see 
657
                  <a class="bodylink" href="/configuration/config-features"
658
                     >Configuration Features</a>): the value used here is the part of the name after
659
                  the last "/", for example <code>--allow-external-functions:off</code>. Only
660
                  features accepting a string or boolean may be set; for booleans the values
661
                  true/false, on/off, yes/no, and 1/0 are recognized.</p>
662
            </td>
663
         </tr>
664
         <tr>
665
            <td>
666
               <p>-?</p>
667
            </td>
668
            <td>
669
               <p>Display command syntax</p>
670
            </td>
671
         </tr>
672
         <tr>
673
            <td>
674
               <p>--?</p>
675
            </td>
676
            <td>
677
               <p>Display a list of features that are available using the <code>--feature:value</code> syntax</p>
678
            </td>
679
         </tr>
680
      </table>
681

    
682
      <h2 class="subtitle">Command line parameters</h2>
683

    
684
      <p>A <i>param</i> takes the form <code>name=value</code>, <i>name</i> being the name of the
685
         parameter, and <i>value</i> the value of the parameter. These parameters are accessible
686
         within the query as external variables, using the <code>$name</code> syntax, provided they
687
         are declared in the query prolog. If there is no such declaration, the supplied parameter
688
         value is silently ignored.</p>
689

    
690
      <p>A <i>param</i> preceded by a leading question mark (<code>?</code>) is interpreted as an
691
         XPath expression. For example, <code>?time=current-dateTime()</code> sets the value of the
692
         external variable <code>$time</code> to the value of the current date and time, as an
693
         instance of <code>xs:dateTime</code>, while <code>?debug=false()</code> sets the value of
694
         the variable <code>$debug</code> to the boolean value <code>false</code>. If the parameter
695
         has a required type (for example <code>declare variable $p as xs:date external;</code>),
696
         then the supplied value must be compatible with this type according to the standard rules
697
         for converting function arguments (it doesn't need to satisfy the stricter rules that apply
698
         to variable initialization). The static context for the XPath expression includes only the
699
         standard namespaces conventionally bound to the prefixes <code>xs</code>, <code>fn</code>,
700
            <code>xsi</code>, and <code>saxon</code>. The static base URI (used when calling the
701
            <code>doc()</code> function) is the current directory. The dynamic context contains no
702
         context item, position, or size, and no variables.</p>
703

    
704
      <p>A <i>param</i> preceded by a leading plus sign (<code>+</code>) is interpreted as a
705
         filename or directory. The content of the file is parsed as XML, and the resulting document
706
         node is passed to the stylesheet as the value of the parameter. If the parameter value is a
707
         directory, then all the immediately contained files are parsed as XML, and the resulting
708
         sequence of document nodes is passed as the value of the parameter. For example,
709
            <code>+lookup=lookup.xml</code> sets the value of the external variable
710
            <code>lookup</code> to the document node at the root of the tree representing the parsed
711
         contents of the file <code>lookup.xml</code>.</p>
712

    
713
      <p>A <i>param</i> preceded by a leading exclamation mark (<code>!</code>) is interpreted as a
714
         serialization parameter. For example, <code>!indent=yes</code> requests indented output,
715
         and <code>!encoding=iso-8859-1</code> requests that the serialized output be in ISO 8859/1
716
         encoding. This is equivalent to specifying the option declaration <code>declare option
717
            saxon:output "indent=yes";</code> or <code>declare option saxon:output
718
            "encoding=iso-8859-1";</code> in the query prolog.</p>
719

    
720
      <aside>If you are using the <code>bash</code> shell, you will need to escape "!" as
721
         "\!".</aside>
722

    
723
      <p>Under Windows, and some other operating systems, it is possible to supply a value
724
         containing spaces by enclosing it in double quotes, for example <code>name="John
725
            Smith"</code>. This is a feature of the operating system shell, not something Saxon
726
         does, so it may not work the same way under every operating system.</p>
727

    
728
      <p>If the parameter name is in a non-null namespace, the parameter can be given a value using
729
         the syntax <code>{uri}localname=value</code>. Here <code>uri</code> is the namespace URI of
730
         the parameter's name, and <code>localname</code> is the local part of the name.</p>
731

    
732
      <p>This applies also to output parameters. For example, you can set the indentation level to 4
733
         by using the parameter <code>!{http://saxon.sf.net/}indent-spaces=4</code>. In this case,
734
         however, lexical QNames using the prefix <code>saxon</code> are also recognized, for
735
         example <code>!saxon:indent-spaces=4</code>. For the extended set of output parameters
736
         supported by Saxon, see <a class="bodylink" href="/extensions/output-extras">Additional
737
            serialization parameters</a>.</p>
738
   </section>
739
   <section id="api-query" title="Running Queries from a Java Application">
740
      <h1>Running Queries from a Java Application</h1>
741

    
742

    
743
      <p>Saxon offers three different APIs allowing queries to be run from Java:</p>
744
      <ul>
745
         <li>
746
            <p>The XQJ interface is an implementation of the XQuery API for Java (XQJ) interface
747
               defined in JSR-225. For information on using this API to invoke the Saxon processor,
748
               see <a href="xqj" class="bodylink">Invoking XQuery using the XQJ API</a>.</p>
749
         </li>
750
         <li>
751
            <p>The s9api interface is a Saxon-specific interface allowing integrated access to all
752
               Saxon's XML processing capabilities in a uniform way, taking advantage of the type
753
               safety offered by generics in Java 5. For information on using this API to invoke the
754
               Saxon processor, see <a href="s9api-query" class="bodylink">Using s9api for
755
                  XQuery</a>.</p>
756
         </li>
757
         <li>
758
            <p>There is also a legacy interface retained from previous Saxon releases, which may be
759
               appropriate if you need access to lower-level Saxon internals. This is described only
760
               in the JavaDoc: start at <a class="javalink"
761
                  href="net.sf.saxon.query.StaticQueryContext">StaticQueryContext</a>.</p>
762
         </li>
763
      </ul>
764

    
765
      <section id="s9api-query" title="Using s9api for XQuery">
766
         <h1>Using s9api for XQuery</h1>
767

    
768
         <p>You can perform a query using the s9api interface as follows:</p>
769
         <ol>
770
            <li>
771
               <p>Create a <a class="javalink" href="net.sf.saxon.s9api.Processor">Processor</a> and
772
                  set any global configuration options on the <code>Processor</code>. If the query
773
               needs any Saxon-PE or Saxon-EE features, use the constructor <code>new Processor(true);</code>.</p>
774
            </li>
775
            <li>
776
               <p>Optionally, build the source document by calling <code>newDocumentBuilder()</code>
777
                  to create a document builder, setting appropriate options, and then calling the
778
                     <code>build()</code> method. This returns an <a class="javalink"
779
                     href="net.sf.saxon.s9api.XdmNode">XdmNode</a> which can be supplied as input to
780
                  the query either as the context item, or as the value of an external variable.</p>
781
            </li>
782
            <li>
783
               <p>Call <code>newXQueryCompiler()</code> to create an <a class="javalink"
784
                     href="net.sf.saxon.s9api.XQueryCompiler">XQueryCompiler</a>. Then set any
785
                  options that are local to a specific compilation (for example, the destination of
786
                  error messages, the base URI, or the character encoding of the query text).</p>
787
            </li>
788
            <li>
789
               <p>Call one of the <code>compile()</code> methods to compile a query. The result is
790
                  an <code>XQueryExecutable</code>, which can be used as often as you like in the
791
                  same thread or in different threads.</p>
792
            </li>
793
            <li>
794
               <p>To run a query, call the <code>load()</code> method on the
795
                     <code>XQueryExecutable</code>. This creates an <a class="javalink"
796
                     href="net.sf.saxon.s9api.XQueryEvaluator">XQueryEvaluator</a>. The
797
                     <code>XQueryEvaluator</code> can be serially reused, but it must not be shared
798
                  across multiple threads. Set any options required for the specific query execution
799
                  (for example, the initial context node, the values of external variables, and the
800
                  destination for the query result), and then call either the
801
                     <code>iterator()</code> or the <code>run()</code> method to execute the
802
                  query.</p>
803
            </li>
804
            <li>
805
               <p>Because the <code>XQueryEvaluator</code> is an <code>Iterable</code>, it is
806
                  possible to iterate over the results directly using the Java "for-each"
807
                  construct.</p>
808
            </li>
809
            <li><p>The result of the <code>XQueryEvaluator.run()</code> method is an
810
            <code>XdmValue</code>. From 9.9 Saxon provides powerful facilities to process
811
            an <code>XdmValue</code> using Java 8 streams. For example, if the query returns
812
            a single node <code>section</code>,(<code>XdmNode</code> is a subclass of <code>XdmValue</code>), then
813
            you could test whether it has any descendant <code>para</code> elements with <code>@class="normal"</code>
814
            by writing <code>if (section.select(descendant("para").where(eq(attribute("class"), "normal")).exists()) {...}</code>.</p>
815
            </li>
816
         </ol>
817

    
818
         <p>The output of the query may be retrieved as an iterator over a sequence of items, or it
819
            may be specified as a <a class="javalink" href="net.sf.saxon.s9api.Destination"
820
               >Destination</a> object, which allows a wide range of possibilities: you can send the
821
            output to a serializer, or to a SAX <code>ContentHandler</code>. You can build a tree
822
            either in Saxon's native format (represented by the s9api class <code>XdmNode</code>) or
823
            as a DOM. You can send the output to be validated against a schema by nominating a <a
824
               class="javalink" href="net.sf.saxon.s9api.SchemaValidator">SchemaValidator</a> as the
825
            destination, or you can pipe it through an XSLT transformation, because <a
826
               class="javalink" href="net.sf.saxon.s9api.XsltTransformer">XsltTransformer</a> also
827
            implements the <code>Destination</code> interface.</p>
828

    
829
         <p>Examples of s9api queries are included in the <code>saxon-resources</code> file, see
830
            module <strong>S9APIExamples.java</strong>.</p>
831
         <h2 class="subtitle">Separate compilation of library modules</h2>
832

    
833
         <p>Under Saxon-EE, it is possible to compile library modules separately from the main
834
            module. This reduces the compilation time and memory usage when the same library module
835
            is imported by many main modules for different queries. A method
836
               <code>compileLibrary()</code> (with a number of overloaded variants supplying the
837
            input in different ways) is provided in the <code>XQueryCompiler</code> class; any
838
            library module compiled using this method will be available to all subsequent
839
            compilations using the same <code>XQueryCompiler</code>. To import the module, simply
840
            use <code>import module</code> specifying the module URI in the normal way. It is not
841
            necessary to supply a module location hint (<code>at "URI"</code>), and if any is
842
            supplied, it will be ignored.</p>
843
      </section>
844

    
845
      <section id="xqj" title="Invoking XQuery using the XQJ API">
846
         <h1>Invoking XQuery using the XQJ API</h1>
847

    
848

    
849
         <p>XQJ (XQuery API for Java, also known as JSR 225) is a vendor-neutral API for invoking
850
            XQuery from Java applications. The Final Release (1.0) is published at <a
851
               href="http://jcp.org/en/jsr/detail?id=225" class="bodylink"
852
               >http://jcp.org/en/jsr/detail?id=225</a>. Saxon includes a complete and conformant
853
            implementation of this API.</p>
854

    
855
         <p>For information on how to use the API, please see the JSR 225 documentation.</p>
856

    
857
         <p>XQJ has many similarities with JDBC, and its general style is that of a client-server
858
            API in which the application opens a "connection" to a database. This of course does not
859
            fit the Saxon in-process model particularly well; on the other hand, apart from the
860
            terminology and the use of some methods (such as the ability to set a connection
861
            timeout) that make little sense in a Saxon context, the API works equally well in an
862
            environment like Saxon where the XQuery processor is invoked directly and runs within
863
            the same Java VM as the client application.</p>
864

    
865
         <p>The samples directory in the issued <code>saxon-resources</code> download file includes
866
            a Java test application, <strong>XQJExamples.java</strong>, which illustrates some of
867
            the possible ways of invoking Saxon using the XQJ interface.</p>
868

    
869
         <p>Note that Saxon will generally only recognize its own implementation of XQJ interfaces.
870
            For example, the interface <a class="javalink"
871
               href="com.saxonica.xqj.SaxonXQDynamicContext">XQDynamicContext</a> includes a method
872
               <code>bindAtomicValue</code> that allows the value of a variable or the context item
873
            to be supplied. The type of the argument is <code>XQItem</code>: however, Saxon will
874
            only accept an <code>XQItem</code> that was created by its own implementations of the
875
            factory methods in <a class="javalink" href="com.saxonica.xqj.SaxonXQDataFactory"
876
               >XQDataFactory</a>.</p>
877

    
878
         <p>Unlike JAXP interfaces, XQJ does not include an implementation-independent factory
879
            class. Instead, you start the process by calling <code>new
880
            SaxonXQDataSource()</code>.</p>
881

    
882
         <p>This constructor will create a new configuration, which will be an
883
               <code>EnterpriseConfiguration</code> or <code>ProfessionalConfiguration</code> if
884
            Saxon-EE or Saxon-PE is in use. As an alternative, there is also a constructor that
885
            allows a specific pre-exising configuration to be used.</p>
886

    
887
         <p>From the <a class="javalink" href="com.saxonica.xqj.SaxonXQDataSource">XQDataSource</a>
888
            you can call <code>getConnection()</code> to get a connection, and from the connection
889
            you can call <code>prepareExpression()</code> to compile a query. The resulting
890
               <code>XQPreparedExpression</code> object has a method <code>executeQuery()</code>
891
            allowing the query to be evaluated. The result of the query evaluation is an
892
               <code>XQSequence</code>, which acts as a cursor or iterator: it has a
893
               <code>next()</code> method allowing you to change the current position, and a
894
               <code>getItem()</code> method allowing you to retrieve the item at the current
895
            position. The result of <code>getItem()</code> is an <code>XQItem</code> object, and
896
            this has methods allowing you to determine the item type, and to convert the item into a
897
            suitable Java object or value.</p>
898
      </section>
899
   </section>
900
   <section id="update" title="Using XQuery Update">
901
      <h1>Using XQuery Update</h1>
902

    
903

    
904
      <p>Saxon-EE supports use of the update extensions to XQuery defined in the W3C Recommendation
905
            <a href="http://www.w3.org/TR/xquery-update-10/" class="bodylink"
906
            >http://www.w3.org/TR/xquery-update-10/</a>.</p>
907

    
908
      <p>Update is available only in Saxon-EE, and is supported only if explicitly requested. The
909
         command line has an option <code>-update:on</code> for this purpose, and all the XQuery
910
         APIs have an option to enable updating, which must be set before compiling the query. If
911
         this option is not set, the parser will not recognize update syntax, and any use of
912
         updating expressions will trigger a syntax error.</p>
913

    
914
      <p>It is possible for an update to modify the document supplied as the context item, or a
915
         document read using the <code>doc()</code> or <code>collection()</code> function, or even a
916
         document constructed dynamically by the query itself. When using the various APIs, the
917
         general policy is that updated documents are never written automatically to disk. Instead,
918
         the list of updated documents is available to the application on completion of the query,
919
         and the application can decide whether to save the documents to their original location, or
920
         to some other location. Documents that were originally read from disk will have a document
921
         URI property which can be used to decide where to write them back.</p>
922

    
923
      <p>When using XQuery Update from the command line, updated documents will be written back to
924
         disk if they have a known document URI, and if that URI is an updatable location (which in
925
         practice means it must be a URI that uses the <code>file://</code> scheme). For testing
926
         purposes, the write-back can be suppressed by using <code>-update:discard</code>. There is
927
         also a <code>-backup</code> option to control whether the old file is saved under a
928
         different name before being overwritten.</p>
929
      <aside>Saxon does no locking to prevent multiple threads attempting to update the same
930
         document. This is entirely a user responsibility.</aside>
931

    
932
      <p>Most errors that can arise during updating operations (for example, inserting two
933
         conflicting attributes) will cause an exception, with the supplied input document in memory
934
         being left in its original state. However, errors detected during the validation phase
935
         (that is, when the updated document is invalid against the schema, assuming revalidation is
936
         requested) are non-recoverable; after such a failure, the state of the document is
937
         unpredictable. Generally the (invalid) updates will have been made, and some of the updates
938
         done during schema validation (setting type annotations and default values) may also have
939
         been made.</p>
940

    
941
      <p>Note that updates to a document will fail unless it is implemented using the <strong>Linked
942
            Tree</strong> model. This can be selected from the command line using
943
            <code>-tree:linked</code>, or via configuration settings in the API. It is not at
944
         present possible to update the Tiny Tree, nor external object models such as DOM, JDOM2, or
945
         XOM.</p>
946
   </section>
947
   <section id="callingfunctions" title="Calling XQuery Functions from Java">
948
      <h1>Calling XQuery Functions from Java</h1>
949

    
950

    
951
      <p>Although the usual way to invoke XQuery from a Java application is to compile and execute a
952
         query as described above, it is also possible to invoke individual XQuery functions
953
         directly from Java if required. This is achieved as follows:</p>
954
         
955
         <ol>
956
            <li><p>First use the s9api interface to create
957
               an <code>XQueryEvaluator</code> in the usual way</p></li>
958
            <li><p>Use methods such as <code>setContextItem()</code> and <code>setExternalVariable()</code>
959
               to supply any information needed by the query</p></li>
960
            <li><p>Then instead of calling the <code>run()</code> method on the <code>XQueryEvaluator</code> 
961
               to execute the query, call the method <code>callFunction()</code> to execute a specific function.</p></li>
962
         </ol>
963
         
964
         <p>The third step can be repeated to call different functions or to call the same function with different
965
            parameters. Having called a function, the context item and external variable values should not be changed.</p>
966
         
967
         <p>A function in a query is identified uniquely by a QName and arity. The QName is supplied explicitly in the call on
968
         <code>callFunction()</code>; the arity is inferred from the length of the argument array.</p>
969
         
970
         <p>The arguments to the function are supplied as an array of <code>XdmValue</code> objects, and the result is returned
971
         as an <code>XdmValue</code>. The <code>XdmValue</code> class has subclasses such as <code>XdmNode</code>, <code>XdmAtomicValue</code>,
972
            and <code>XdmMap</code> allowing specific types of value to be constructed; it is also possible, of course, to use the
973
            result of one function call as an argument to another function call.</p>
974
      
975
            <p>Saxon applies the standard function conversion rules to convert supplied arguments to the
976
         required type: for example, if the function expects a string, then you can supply an attribute node, and it will be atomized.</p>
977

    
978
      <p>Here is an example:</p>
979
         <samp><![CDATA[Processor processor = new Processor(true);
980
XQueryCompiler qc = processor.newXQueryCompiler();
981
XQueryExecutable exp1 = qc.compile(
982
        "declare function local:t1($v1 as xs:integer, $v2 as xs:double*) { " +
983
        "   $v1 div sum($v2)" +
984
        "};" +
985
        "10");
986
final XQueryEvaluator ev = exp1.load();
987
XdmValue v1 = new XdmAtomicValue(14);
988
XdmValue v2 = new XdmAtomicValue(5).append(new XdmAtomicValue(2));
989
XdmValue result = ev.callFunction(new QName("http://www.w3.org/2005/xquery-local-functions", "t1"), new XdmValue[]{v1, v2});]]></samp>
990
      
991
      <p>The value of <code>result</code> will be the atomic value 2, of type <code>xs:double</code>. The function conversion rules take care of
992
      the fact that a supplied sequence of integers is accepted where the required type is a sequence of <code>xs:double</code> values.</p>
993
         
994
         
995
         <aside>Earlier Saxon releases provided a lower-level interface for function calling, using the method
996
      <code>StaticQueryContext.getUserDefinedFunction()</code> to obtain a <code>UserFunction</code> object, and
997
      then using the <code>call()</code> method on the <code>UserFunction</code> object to invoke it. That approach
998
      was very efficient but not very robust (for example, it did no type-checking on the supplied arguments)
999
      and it was therefore dropped.</aside>
1000
   </section>
1001
   <section id="resultformat" title="Result Format">
1002
      <h1>Result Format</h1>
1003

    
1004

    
1005
      <p>The result of a query is a sequence of nodes and atomic values - which means it is not, in
1006
         general, an XML document. This raises the question as to how the results should be
1007
         output.</p>
1008

    
1009
      <p>The Saxon command line processor for XQuery by default produces the output in raw format.
1010
         This converts the result sequence to a document following the rules of the XQuery
1011
            <code>document{}</code> constructor, and then serializes this document.</p>
1012

    
1013
      <p>The alternative is wrapped format, requested using the <code>-wrap</code> argument. This
1014
         wraps the result sequence as an XML document, and then serializes the resulting document.
1015
         Each item in the result sequence is wrapped in an element (such as
1016
            <code>result:element</code> or <code>result:atomic-value</code>) according to its type.
1017
         The sequence as a whole is wrapped in a <code>result:sequence</code> element.</p>
1018
   </section>
1019
   <section id="querycompilation" title="Compiling Queries">
1020
      <h1>Compiling Queries</h1>
1021

    
1022
      <aside>Bycode generation requires Saxon-EE.</aside>
1023

    
1024
      <p>Since Saxon 9.4, Saxon-EE automatically (and selectively) compiles queries to Java
1025
         bytecode. When running on .NET, the bytecode is then automatically converted to IL code for
1026
         execution. The bytecode exists only in memory, and would not be useful otherwise because it
1027
         contains many references to the data structures generated by the Saxon parser and
1028
         optimizer.</p>
1029

    
1030
      <p>This facility replaces the ability in previous Saxon-EE releases to generate Java source
1031
         code from a query.</p>
1032
      
1033
      <p>From Saxon 9.8, bytecode generation is by default applied only to hotspots, that is, parts of the 
1034
         executable code that are found to be frequently executed. These will often be predicates in filter
1035
         expressions. The threshold for generating bytecode is configurable. Bytecode generation can be monitored
1036
      using the <code>-TB</code> option on the command line.</p>
1037

    
1038
      <p>The performance boost achieved by bytecode generation is variable; 25% is typical. The
1039
         constructs that benefit the most are those where the expression tree contains many
1040
         constructs that are relatively cheap in themselves, such as type conversion, comparisons,
1041
         and arithmetic. This is because the saving from bytecode generation is mainly not in the
1042
         cost of performing primitive operations, but in the cost of deciding which operations to
1043
         perform: so the saving is greater where the number of operations is high relative to their
1044
         average cost.</p>
1045

    
1046
      <p>There are configuration options to suppress bytecode generation
1047
            (<code>Feature.GENERATE_BYTE_CODE</code>), to insert debugging logic into the
1048
         generated bytecode (<code>Feature.DEBUG_BYTE_CODE</code>), and to display the generated
1049
         bytecode (<code>Feature.DISPLAY_BYTE_CODE</code>). See <a class="bodylink"
1050
            href="/configuration/config-features">Configuration Features</a> for more
1051
         information.</p>
1052
   </section>
1053
   <section id="performanceanalysis" title="Performance Analysis">
1054
      <h1>Performance Analysis</h1>
1055
      <p>Saxon comes with a simple tool allowing profiling of the execution time in a
1056
         query.</p>
1057
      <p>To run this tool, first execute the query with the <code>-TP:filename</code>
1058
         option, which will gather timed tracing information and create a profile report to the
1059
         specified file (or to the standard error output if no filename is given). For example:</p>
1060
      <kbd>java   net.sf.saxon.Query   -TP:profile.html   -q:<i>queryfile</i>  
1061
      </kbd>
1062
      <p>Then view the resulting <code>profile.html</code> file in your browser.</p>
1063
      <p>The output identifies functions and global variables in the original query by their name,
1064
         line number, and the last few characters of the URI of their module. For
1065
         each instruction it gives the number of times the instruction was executed, the average
1066
         time in milliseconds of each execution, and the total time. Timings are given both gross
1067
         (the time for a function including all the functions it calls recursively), and net (the
1068
         time for a function excluding time in its called functions). The table is sorted according
1069
         to a weighting function that attempts to put the dominant functions and global variables at the
1070
         top. These will not necessarily be those with the greatest time, which tend to be
1071
         instructions that were only executed once but remained active for the duration of the
1072
         query.</p>
1073
   </section>
1074
   <section id="extensibility" title="Extensibility">
1075
      <h1>Extensibility</h1>
1076

    
1077

    
1078
      <p>The Saxon XQuery implementation allows you to call Java methods as external functions. The
1079
         function does not need to be declared. Use a namespace declaration such as <code>declare
1080
            namespace math="java:java.lang.Math"</code>, and invoke the method as
1081
            <code>math:sqrt(2)</code>.</p>
1082

    
1083
      <p>More details of this mechanism are found in <a class="bodylink"
1084
            href="/extensibility/functions">Writing Extension Functions</a>.</p>
1085

    
1086
      <p>Saxon recognizes the XQuery pragma syntax, but it currently defines only one pragma of its
1087
         own, the <code>saxon:validate-type</code> pragma (see <a class="bodylink"
1088
            href="../extensions">Extensions</a>), and this is now redundant since the equivalent
1089
         facility is standard in XQuery 3.0. Saxon will adopt the correct fallback behavior if
1090
         presented with a query that uses another vendor's extensions, provided these are designed
1091
         in conformance with the W3C pragma specification.</p>
1092
      
1093
      <p>A function may be marked as a memo function either by using the function annotation
1094
      <code>%saxon:memo-function</code> or by preceding the function declaration with the
1095
         option declaration <code>declare option saxon:memo-function</code>.</p>
1096

    
1097
      <p>Saxon recognizes the XQuery option declaration syntax. Several specific option
1098
         declarations are provided, but most of these are obsolete:</p>
1099
      
1100
      <ul>
1101
         <li><code>declare option saxon:default</code> declares a default
1102
            value for external variables (query parameters). No longer needed in
1103
         XQuery 3.0, which provides native syntax for declaring default values.</li>
1104
         <li><code>declare option saxon:output</code>
1105
            declares a serialization parameter. Superseded by <code>declare option output:XXXXX</code>.</li>
1106
         <li><code>declare option saxon:memo-function</code>
1107
            defines whether the following function declaration is to be implemented as a memo function;
1108
         superseded by the function annotation <code>%saxon:memo-function</code>.</li>
1109
      </ul>
1110
      <p>Any other option declaration in the Saxon namespace is ignored with a warning; an option
1111
         declaration in any other namespace is ignored silently.</p>
1112
   </section>
1113
   <section id="extensions" title="Extensions">
1114
      <h1>XQuery Extensions</h1>
1115

    
1116

    
1117
      <p>The full library of Saxon, EXSLT and EXPath functions described in <a class="bodylink"
1118
            href="/extensions">Extensions</a> is available, except for those (for example, some
1119
         forms of <code>saxon:serialize</code>) that have an intrinsic dependency on an XSLT
1120
         stylesheet.</p>
1121
     
1122
     <p>The XPath syntax extensions described in <a class="bodylink"
1123
       href="/extensions/syntax-extensions">Syntax Extensions</a> are also available in XQuery.</p>
1124
     
1125
      <h2 class="subtitle">declare option saxon:default</h2>
1126

    
1127
      <aside>
1128
         This extension is obsolete, as the functionality is available from Saxon 9.2 onwards
1129
            using the syntax in the XQuery 3.0 specification.
1130
      </aside>
1131

    
1132
      <p>An XQuery option declaration is defined allowing a default value to be specified for a
1133
         query parameter (external variable). The syntax is illustrated below:</p>
1134
      <samp><![CDATA[declare namespace saxon="http://saxon.sf.net/";
1135
declare option saxon:default "20";
1136
declare variable $x external;
1137
]]></samp>
1138

    
1139
      <p>The default value is written as an XPath expression. The surrounding quotes are part of the
1140
         "declare option" syntax, not part of the expression: therefore, if the default value is to
1141
         be supplied as a string literal, two sets of quotes are needed.</p>
1142
      <p>From XQuery 3.0, the above syntax can be replaced by:</p>
1143
      
1144
      <samp><![CDATA[declare variable $x external := 20;]]></samp>
1145
      <h2 class="subtitle">declare option saxon:output</h2>
1146
      
1147
      <aside>
1148
         From XQuery 3.0, standard serialization parameters can be set using
1149
         <code>declare option output:XXXX</code>. Saxon-specific option declarations
1150
         are still needed for Saxon-specific serialization parameters such as
1151
         <code>saxon:double-space</code>.
1152
      </aside>
1153

    
1154
      <p>Saxon provides an option declaration to set serialization parameters. This takes the form
1155
         shown in the following example:</p>
1156
      <samp><![CDATA[declare namespace saxon="http://saxon.sf.net/";
1157
declare option saxon:output "method=html";
1158
declare option saxon:output "saxon:indent-spaces=1";
1159
]]></samp>
1160

    
1161
      <p>All the standard serialization parameters described in the <a
1162
         href="http://www.w3.org/TR/xslt-xquery-serialization-31/" class="bodylink">W3C
1163
            Serialization specification</a> are available</p>
1164
      <ul>
1165
         <li>
1166
            <p>allow-duplicate-names</p>
1167
         </li>
1168
         <li>
1169
            <p>build-tree</p>
1170
         </li>
1171
         <li>
1172
            <p>byte-order-mark</p>
1173
         </li>
1174
         <li>
1175
            <p>cdata-section-elements</p>
1176
         </li>
1177
         <li>
1178
            <p>doctype-public</p>
1179
         </li>
1180
         <li>
1181
            <p>doctype-system</p>
1182
         </li>
1183
         <li>
1184
            <p>encoding</p>
1185
         </li>
1186
         <li>
1187
            <p>escape-uri-attributes</p>
1188
         </li>
1189
         <li>
1190
            <p>html-version</p>
1191
         </li>
1192
         <li>
1193
            <p>include-content-type</p>
1194
         </li>
1195
         <li>
1196
            <p>indent</p>
1197
         </li>
1198
         <li>
1199
            <p>item-separator</p>
1200
         </li>
1201
         <li>
1202
            <p>json-node-output-method</p>
1203
         </li>
1204
         <li>
1205
            <p>media-type</p>
1206
         </li>
1207
         <li>
1208
            <p>method</p>
1209
         </li>
1210
         <li>
1211
            <p>normalization-form</p>
1212
         </li>
1213
         <li>
1214
            <p>omit-xml-declaration</p>
1215
         </li>
1216
         <li>
1217
            <p>standalone</p>
1218
         </li>
1219
         <li>
1220
            <p>suppress-indentation</p>
1221
         </li>
1222
         <li>
1223
            <p>undeclare-prefixes</p>
1224
         </li>
1225
         <li>
1226
            <p>use-character-maps</p>
1227
         </li>
1228
         <li>
1229
            <p>version</p>
1230
         </li>
1231
      </ul>
1232

    
1233
      <p>In addition some Saxon-specific serialization parameters are available: see <a
1234
            class="bodylink" href="/extensions/output-extras">Additional serialization
1235
            parameters</a>.</p>
1236
      <h2 class="subtitle">declare option saxon:memo-function</h2>
1237

    
1238
      <p>Saxon provides an option declaration to treat the immediately following function as a
1239
         memo-function. This takes the form shown in the following example:</p>
1240
      <samp><![CDATA[declare namespace saxon="http://saxon.sf.net/";
1241
declare option saxon:memo-function "true";
1242
declare function local:factorial($n as xs:integer) as xs:integer {
1243
  local:factorial($n - 1) * n
1244
};
1245
]]></samp>
1246
      
1247
      <p>Alternatively:</p>
1248
      
1249
      <samp><![CDATA[declare namespace saxon="http://saxon.sf.net/";
1250
declare %saxon:memo-function function local:factorial($n as xs:integer) as xs:integer {
1251
  local:factorial($n - 1) * n
1252
};
1253
]]></samp>
1254

    
1255
      <p>A memo function remembers the results of previous calls, so if it is called twice with the
1256
         same arguments, it will not repeat the computation, but return the previous result.</p>
1257

    
1258
      <p>The allowed values of the option are "true" and "false" (the default is false), and any
1259
         other value is ignored with a warning.</p>
1260
      <h2 class="subtitle">declare option saxon:allow-cycles</h2>
1261
      
1262
      <p>In XQuery 1.0, it was an error XQST0093 for a function or variable in module A to reference a function
1263
         or variable in module B if there is a function or variable in module B that references one
1264
         in A. This restriction was dropped in XQuery 3.0. Saxon introduced the option <code>declare option saxon:allow-cycles
1265
            "true"</code> to disable the check in XQuery 1.0. The option also disables error XQST0073, which
1266
         otherwise occurs when two modules in different namespaces import each other.</p>
1267

    
1268
      <p>The allowed values of the option are "true" and "false" (the default is false), and any
1269
         other value is ignored with a warning.</p>
1270

    
1271
      <p>This option does not disable the check for cycles that would actually cause execution to
1272
         fail, for example a global variable <code>$V1</code> whose initializer uses
1273
            <code>$V2</code>, when <code>$V2</code> similarly depends on <code>$V1</code>.</p>
1274

    
1275
      <p>Note that this option declaration must be written <i>after</i> the module imports, but
1276
         before any variable or function declarations.</p>
1277
      <h2 class="subtitle">The saxon:validate-type pragma</h2>
1278

    
1279
      <p>
1280
         <i>This extension is largely obsolescent: since version 9.3, Saxon implements the XQuery
1281
            3.0 syntax for validation by type. The extension does serve one remaining purpose, which
1282
            is to allow attributes to be validated. (The standard syntax requires an element or
1283
            document node.)</i>
1284
      </p>
1285

    
1286
      <p>Saxon-EE provides a pragma (a language extension) to allow constructed elements to be
1287
         validated against a schema-defined global type definition. The standard
1288
            <code>validate</code> expression allows validation only against a global element
1289
         declaration, but some schemas (an example is FpML) provide very few global elements, and
1290
         instead rely heavily on locally-declared elements having a global type. This makes it
1291
         impossible to construct fragments of an FpML document in a way that takes advantage of
1292
         static and dynamic type checking.</p>
1293

    
1294
      <p>The extension takes the form:</p>
1295
      <samp><![CDATA[(# saxon:validate-type my:personType #) { expr }
1296
]]></samp>
1297

    
1298
      <p>Conceptually, it makes a copy of the result of evaluating <code>expr</code> and validates
1299
         it against the named schema type, causing the copied nodes to acquire type annotations
1300
         based on the validation process. The effect is the same as that of the <code>type</code>
1301
         attribute in XSLT instructions such as <code>xsl:element</code> and
1302
            <code>xsl:copy-of</code>. The schema type (shown in the above example as
1303
            <code>myPersonType</code>) may be a simple type or a complex type defined in an imported
1304
         schema, or a built-in type; it is written as a QName, using the default namespace for
1305
         elements and types if it is unprefixed.</p>
1306

    
1307
      <p>Note that XQuery processors other than Saxon will typically ignore this pragma, and return
1308
         the value of <code>expr</code> unchanged. Such processors will report type-checking
1309
         failures if the value is used in a context where the required type is <code>element(*,
1310
            type-name)</code>.</p>
1311

    
1312
      <p>You can use a different namespace prefix in place of <code>saxon</code>, but it must be
1313
         bound using a namespace declaration to the namespace
1314
         <code>"http://saxon.sf.net/"</code>.</p>
1315

    
1316
      <p>Here is a complete example:</p>
1317
      <samp><![CDATA[module namespace time="http://www.example.com/module/hour-minute-time";
1318
declare namespace saxon="http://saxon.sf.net/";
1319
import schema namespace fpml = "http://www.fpml.org/2005/FpML-4-2" at "....";
1320

    
1321
declare function time:getCurrentHourMinuteTime() as element(*, fpml:HourMinuteTime) {
1322
    let $time = string(current-time())
1323
    return
1324
        (# saxon:validate-type fpml:HourMinuteTime #) {
1325
            <time>{substring($time, 1, 5)}:00</time>
1326
        }
1327
};        
1328
]]></samp>
1329

    
1330
      <p>Saxon ignores any pragmas in a namespace other than the Saxon namespace; it rejects any
1331
         pragmas whose QName is ill-formed, as well as pragmas in the Saxon namespace whose local
1332
         name is not recognized.</p>
1333

    
1334
      <p>The construct also allows validation of attributes against a simple type definition, for
1335
         example:</p>
1336
      <samp><![CDATA[module namespace time="http://www.example.com/module/hour-minute-time";
1337
declare namespace saxon="http://saxon.sf.net/";
1338
import schema namespace fpml = "http://www.fpml.org/2005/FpML-4-2" at "....";
1339

    
1340
declare function time:getCurrentHourMinuteTime() as attribute(*, fpml:HourMinuteTime) {
1341
    let $time = string(current-time())
1342
    return (# saxon:validate-type fpml:HourMinuteTime #) {
1343
       attribute time {concat(substring($time, 1, 5), ':00')}
1344
    }
1345
};        
1346
]]></samp>
1347
   </section>
1348
   <section id="usecases" title="Use Cases">
1349
      <h1>Use Cases</h1>
1350

    
1351

    
1352
      <p>Saxon runs all the <a href="http://www.w3.org/TR/xquery-use-cases" class="bodylink">W3C
1353
            XQuery Use Cases</a>.</p>
1354

    
1355
      <p>The relevant queries (some of which have been corrected from those published by W3C) are
1356
          included in the <code>saxon-resources</code> download (folder <code>use-cases</code>) together with batch
1357
         scripts for running them. A few additional use cases have been added to show features that
1358
         would otherwise not be exercised. A separate script is available for running the STRONG use
1359
         cases since these require Saxon-EE.</p>
1360

    
1361
       <p>Also included in the <code>saxon-resources</code> download is a query <code>samples/query/tour.xq</code>. This is a
1362
         query that generates a knight's tour of the chessboard. It is written as a demonstration of
1363
         recursive functional programming in XQuery. It requires no input document. You need to
1364
         supply a parameter on the command line indicating the square where the knight should start,
1365
         for example <code>start=h8</code>. The output is an HTML document. For more details, see
1366
         the <a class="bodylink" href="/samples/tour">Knight's Tour</a> sample information.</p>
1367
   </section>
1368
</article>
(17-17/19)