XQuery and XSLT Reference Guide — Chapter 3

try/catch Expression

The try/catch extension allows you to catch and handle exceptions. MarkLogic Server exceptions are thrown in XML format, and you can apply an XPath statement to the exception if there is a particular part you want to extract. The exception is bound to the variable in the catch clause.

The following code sample uses a try/catch block to catch exceptions upon loading a document, and prints out the filename if an exception occurs.

try {
     let $filename := "/space/myfile.xml"
     let $options := <options xmlns="xdmp:document-load">
                         <uri>/myfile.xml</uri>
                         <repair>none</repair>
                      </options>
     return xdmp:document-load($filename, $options)
     }
catch ($exception) {
"Problem loading file, received the following exception: ",
$exception }

Most exceptions can be caught with a try/catch block, but the XDMP-CANCELED, SVC-CANCELED, and XDMP-DISABLED exceptions cannot be caught in a try/catch block.

Function Mapping

Function mapping is an extension to XQuery that allows you to pass a sequence to a function parameter that is typed to take a singleton item, and it will invoke that function once for each item in the sequence. This section describes function mapping and includes the following parts:

• Understanding Function Mapping
• Enabling or Disabling Function Mapping

xquery version "1.0-ml";

declare function local:print-word ($word as xs:string) { $word };

local:print-word( ("hello", "world") )
(: 
   evaluates the print-word function twice, once for "hello" 
   and once for "world", returning hello world 
:)

xquery version "1.0-ml";
(1 to 2) * (3 to 4)
(: returns the sequence (3, 4, 6, 8) :) 

xquery version "1.0-ml";

declare function local:print-word ($word as xs:string) { $word };

local:print-word( () )
(: 
   evaluates the print-word function zero times, resulting 
   in the empty sequence
:)

declare namespace xdmp="http://marklogic.com/xdmp";
declare option xdmp:mapping "true";

declare option xdmp:mapping "false";

Semi-Colon as Transaction Separator

In the enhanced dialect, you can add a semi-colon after one or more XQuery statements in the body of a main module and then add another one or more XQuery statement. The two sets of statements are then evaluated as two separate transactions. Each set of statements must be a main module; that is, they must all have their own prolog elements. All of the statements in the program must use the same XQuery dialect. For example, the following creates a document and then returns the contents of the document:

xquery version "1.0-ml";
xdmp:document-insert("/mydocs/sample.xml", 
            <some-element>content</some-element>) ;
xquery version "1.0-ml";
(: Note that the XQuery version must be the same for all 
   statements in the module :)
fn:doc("/mydocs/sample.xml")
(: returns the document created in the previous statement :)

Note that you cannot use the semi-colon as a transaction separator in the strict XQuery dialect (1.0). For more details on transactions, see Understanding Transactions in MarkLogic Server chapter in the Application Developer's Guide.

Private Function and Variable Definitions

In the 1.0-ml enhanced dialect, you can create library modules with functions and variables that are private to the library module. Private functions and variables are useful when you have certain code you do not want to expose to users of the library, but might be useful for functions for the library to use. To make functions and variables private, add private to the function or variable declaration syntax as follows:

declare private function ....
declare private variable ....

Note that functions and variables in a main module are private by definition, so declaring them private only makes sense for library modules.

Functions With Side Effects

The XQuery specification defines that XQuery programs produce only their return values, without producing any side effects; that is, without causing any changes to the run-time environment as a result of running the program (with the exception of fn:trace). MarkLogic Server has many enhancements that cause side effects. For example, there are functions that insert or update documents in a database. Since functions like the ones that update documents do more than functions that simply return values, they are extensions to the XQuery specification.

Side effects are extremely useful when building applications. Therefore, MarkLogic Server includes many functions that have side effects. The following are some examples of functions with side effects:

• xdmp:set
• Update Built-ins (xdmp:document-load, xdmp:node-insert, and so on)
• Administrative functions (xdmp:merge, Admin library, xdmp:shutdown, and so on)

Shorthand Positional Predicate Syntax

MarkLogic Server enhanced mode supports the shorthand version of the positional predicate syntax, where you can specify the position numbers to include. For example, the following specifies the first three items in the sequence:

xquery version "1.0-ml";
(1, 2, 3, 4, 5, 5)[1 to 3]

In XQuery 1.0 strict mode (1.0), you must use the fn:position() function as in the following example:

xquery version "1.0";
(1, 2, 3, 4, 5, 5)[fn:position() = (1 to 3)]

Binary Node Constructor and Node Test

MarkLogic Server enhanced mode extends the XQuery types to include a binary node type. Binary nodes are used to store binary documents. To support this type, the MarkLogic Server enhanced XQuery dialect includes a node constructor (binary) to construct a binary node and a node test (binary()) to test whether a node is a binary node (for example, in a typeswitch expression). These extensions are not available in the 1.0 dialect.

validate as Expression

In the 1.0-ml dialect, you can use the validate as syntax to specify the type for a validate expression. The validate as expression is an extension to the XQuery 1.0 validate expression, and it is only available in 1.0-ml; it is not available in the 1.0 dialect. For details on the validate expression, see Validate Expression.

Serialization Options

You can set the serialization options in XQuery with the declare option XQuery prolog. In XSLT, you can set the serialization options using the <xsl:output> instruction. For details on setting the serialization options in XQuery, see Declaring Options. For XSLT output details, see the XSLT specification (http://www.w3.org/TR/xslt#output).

Importing a Stylesheet Into an XQuery Module

Using the 1.0-ml dialect, you can import a XSLT stylesheet into an XQuery module, allowing you access to the functions and variables defined defined by that stylesheet. To import a stylesheet in XQuery, use a prolog expression of the following form:

import stylesheet at "/path-to-stylesheet.xsl";

The following example shows an XQuery module that imports a stylesheet and runs a function in the stylesheet:

xquery version "1.0-ml";

(: assumes a stylesheet at /f.xsl with the following contents:
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
   version="2.0" 	xmlns:foo="foo">
	<xsl:function name="foo:foo">foo</xsl:function>
</xsl:stylesheet>
:)

import stylesheet at "/f.xsl";
declare namespace foo="foo";

foo:foo()

(: Returns the string:
foo 
which is the output of the 
stylesheet function. :)

Similarly, you can import an XQuery module into an XSLT stylesheet, as described in Importing XQuery Function Libraries to a Stylesheet.

To use functions and variables from a stylesheet in XQuery, they should be defined in a namespace in the stylesheet. In XQuery, it is difficult to call functions and variables in no namespace. Therefore, the best practice is, for functions and variables in a stylesheet that you plan to import into an XQuery module, define them in a namespace. Note that in an XQuery library module, all function and variable declarations must be in a namespace.

Implementation-Defined Semantics

The XQuery specification lists a number of items that are allowed to be defined by each implementation of XQuery:

http://www.w3.org/TR/xquery/#id-impl-defined-items

This section describes the following implementation-defined items as they are implemented in MarkLogic Server:

• Automatic Namespace Imports for Predefined Namespaces
• External Variables
• Collations
• Implementation-Defined Primitive XQuery Types
• Decimal Precision at Least 18 Digits, and is Not Configurable
• Library Modules Default Function Namespace Defaults to Library Namespace

  Except where noted, the items in this section apply all of the XQuery dialects supported in MarkLogic Server.

declare variable $my:variable as xs:string* external;

declare variable $my:variable as xs:string* external 
  := "default value";

xquery version "1.0-ml";
declare namespace my="myNamespace";
declare variable $my:variable as xs:string* external;

fn:concat("The value of $my:variable is: ", $my:variable)

xquery version "1.0-ml";
declare namespace my="myNamespace";

xdmp:invoke("/extvar.xqy", (xs:QName("my:variable"), "my value"))

The value of $my:variable is: my value