Prerequisites

You may find usefull to configure your environnment by using an alias, so that the command of this tutorial appears simpler.
The following definition is for Bash shell:

alias drb='java -jar [DRB_INSTALLATION_HOME]/lib/java/drb-[M]-[m]-[t].jar'

General Content of an XQuery script

First of all, here is just a small definition of what an XQuery script file is:

• A text file (usually with a filename suffix equal to .xql)
• Containing XQuery instructions

For example please consider the following script script_simple.xql :

xquery version "1.0";

let $var_number := 1234
let $var_text   := "Some text"
let $var_node   := <my_var_node>The node content</my_var_node>


return

<output>
   <number>{ $var_number }</number>
   <text>{ $var_text }</text>
   <nodeComplet>{ $var_node }</nodeComplet>
   <nodeContent>{ fn:data($var_node) }</nodeContent>
</output>

Let looks in detail to the content of this script:

xquery version "1.0";

let $var_number := 1234
let $var_text   := "Some text"
let $var_node   := <my_var_node>The node content</my_var_node>

return

<output>
   <number>{ $var_number }</number>
   <text>{ $var_text }</text>
   <nodeComplet>{ $var_node }</nodeComplet>
   <nodeContent>{ fn:data($var_node) }</nodeContent>
</output>

Executing a script

An XQuery script is usually executed on command line using the option --query-file (or -f for the short option name).

For example executing the script presented in the previous section will be done using the command:

drb --query-file script_simple.xql

May return:

<output>
   <number>1234</number>
   <text>Some text</text>
   <nodeComplet>
      <my_var_node>The node content</my_var_node>
   </nodeComplet>
   <nodeContent>The node content</nodeContent>
</output>

Using external variable

External variable are entered by user (or program) at execution time contrary to standard variable. For example this allow to ask the user some info dynamically.

Consider the script: script_external_variable.xql :

xquery version "1.0";

declare variable $user_input as xs:string? external;


fn:concat("User input is: ", $user_input)

Lets execute the script using the command:

drb --query-file script_external_variable.xql -variable user_input ABC

May return:

User input is: ABC

Using comments

Comments are used to add some textual content to your script in order to add free text in any place you think to be of interest. These comments are ignored during the execution phase.

In the XQuery language comments are introduce by (: (opening a comments section) and :) (closing a comments section).

For example script_comments.xql :

xquery version "1.0";

let $var_number := 1234

return

   (: My XQuery script is used to double the var_number! :)
   $var_number * 2

Take care that if you are in an HTML part in your script this former comments symbol will not work. Instead you may used the HTML comments (<!-- and -->).

WARNING: HTML comments are not already supported by DRB APIŽ in this context.

Using function

A function can be reused several time in the same script.

Consider the script: script_function.xql :

xquery version "1.0";

(: This function take a string as input and return it surrounded by stars '*' :)
declare function addStars($str as xs:string) as xs:string
{
   fn:concat("***", $str, "***")
};



(: The script make use of its function :)
fn:concat( addStars("some input string"), "  ", addStars("some other string"))

Lets execute the script using the command:

drb --query-file script_function.xql

May return:

***some input string***  ***some other string***

Using modules

A module allow to re-use a set of functions and variables define is a specified XQuery script.

In order to be used it must be imported in your current script.

Consider the module script (see it like a library ): script_module_def.xql :

module namespace mydemomodule = "libraryDemoModuleURI";

declare variable $mydemomodule:myvar := 54321;

declare function mydemomodule:add ($a as xs:integer, $b as xs:integer) as xs:integer
{
  ($a + $b)
};

Consider the script that will make use of the module script: script_module.xql :

xquery version "1.0";

import module namespace mns = "libraryDemoModuleURI" at "./script_module_def.xql";

let $var_num := 1234

return

   fn:concat("The sum of ", $mns:myvar, " and ", $var_num, " is: ", 
             mns:add($mns:myvar, $var_num))

Lets execute the script using the command:

drb --query-file script_module.xql

May return:

The sum of 54321 and 1234 is: 55555