Function calls

A function call consists of a QName that is followed by a parenthesized list of zero or more expressions, which are called arguments. Db2 XQuery supports calls to built-in XQuery functions and Db2 built-in functions.

Built-in XQuery functions are in the namespace http://www.w3.org/2005/xpath-functions, which is bound to the prefix fn. Db2 built-in functions are in the namespace http://www.ibm.com/xmlns/prod/db2/functions, which is bound to the prefix db2-fn. If the QName in the function call has no namespace prefix, the function must be in the default function namespace. The default function namespace is the namespace of built-in XQuery functions (bound to the prefix fn) unless the namespace is overridden by a default function declaration in the query prolog.

Important: Because the arguments of a function call are separated by commas, you must use parentheses to enclose argument expressions that contain top-level comma operators.

The following steps explain the process that Db2 XQuery uses to evaluate functions:

  1. Db2 XQuery evaluates each expression that is passed as an argument in the function call and returns a value for each expression.
  2. The value that is returned for each argument is converted to the data type that is expected for that argument. When the argument expects an atomic value or a sequence of atomic values, Db2 XQuery uses the following rules to convert the value of the argument to its expected type:
    1. Atomization is applied to the given value. This results in a sequence of atomic values.
    2. Each item in the atomic sequence that is of type xdt:untypedAtomic is cast to the expected atomic type. For built-in functions that expect numeric arguments, arguments of type xdt:untypedAtomic are cast to xs:double.
    3. Numeric type promotion is applied to any numeric item in the atomic sequence that can be promoted to the expected atomic type. Numeric items include items of type xs:integer (or derived from xs:integer), xs:decimal, xs:float, or xs:double.
    4. If the expected type is xs:string, each item in the atomic sequence that is of type xs:anyURI, or derived from xs:anyURI, is promoted to xs:string
  3. The function is evaluated using the converted values of its arguments. The result of the function call is either an instance of the function's declared return type or an error.

Examples

Function call with a string argument: The following function call takes an argument of type xs:string and returns a value of type xs:string in which all characters are in uppercase:
fn:upper-case($ns1_customerinfo/ns1:addr/@country)

In this example, the argument that is passed to the fn:upper-case function is a path expression. When the function is invoked, the path expression is evaluated and the resulting node sequence is atomized. Each atomic value in the sequence is cast to the expected type, xs:string. The function is evaluated and returns a sequence of atomic values of type xs:string.

Function call with a sequence argument: The following function takes a sequence, (1, 2, 3), as the single argument. 
fn:max((1, 2, 3))
Because the function fn:max expects a single argument that is a sequence of atomic values, nested parentheses are required. The returned value is 3.