Two methods are available for specifying the values of implementation-specific settings in the query itself: option declarations and extension expressions. This section describes how these settings are defined and used. The documentation for your XQuery implementation should provide information on what specific options and extensions it supports.
An option declaration can be used to specify an implementation-defined setting in the query prolog. This is useful for settings that affect the entire query, or other settings in the prolog. The syntax of an option declaration is shown in Figure 23-1.
The Saxon implementation allows for several different types of options. Example 23-1 shows two of them.
Example 23-1. Option declarations
declare namespace saxon="http://saxon.sf.net/"; declare option saxon:default "25"; declare variable $maxRowsToReturn external; declare option saxon:output "method=xhtml";
The first option declaration, for saxon:default, is used to specify a default value for the global variable whose declaration follows it. If no value is supplied for $maxRowsToReturn outside the scope of the query, the value 25 is used. The second option declaration, for saxon:output, is used to specify values for serialization parameters, in this case, the output method when serializing the results. Serialization parameters are discussed in Chapter 22.
An option declaration may apply to the whole query, or just the subsequent prolog declaration, or any other scope defined by the implementation.
Options have namespace-qualified names, which means that the prefixes used must be declared, and processors recognize them by their namespace. If an option belongs to a namespace that is not supported by the implementation, it is ignored. If a processor recognizes the option but determines that the content is invalid, the behavior is implementation-dependent. It may raise an error, or it may ignore it.
Queries can also contain implementation-specific extension expressions that may be used to specify additional parameters to a query. Extensions are similar to options, except that they can appear anywhere that an expression is allowed in the query (not just the prolog) and they apply to an individual expression.
For example, the extension:
(# datypic:timeOut 200 #)
{ count($doc//author) }might be used to tell the processor to time out after 200 seconds. The syntax of an extension is shown in Figure 23-2.
Extension expressions consist of one or more pragmas, each delimited by (# and #), followed by the affected expression in curly braces. A pragma has two parts: a qualified name, and optional content, which can be any string of characters (except for #)).
Extensions can be used in a number of ways. Examples include:
Providing hints to the processor regarding how best to evaluate the expression, such as what index to use or how long to wait before timing out.
Allowing nonstandard interpretation of XQuery syntax, for example, allowing the comparison of
xs:gDayvalues using the<operator, which is normally not permitted. However, the expression in curly braces still must use valid XQuery syntax.Specifying an alternate proprietary syntax in the pragma content that may be more efficient or otherwise preferable to the expression in curly braces.
Like options, pragmas are recognized by their namespace, and a processor will ignore any pragmas in namespaces it doesn't recognize. If all the pragmas associated with an expression are ignored, the expression is evaluated normally, as if no pragmas were specified.
If a processor recognizes the namespace used in a pragma, but not the local name, it may either raise an error or ignore it.