XMLQUERY 标量函数

该模式是 SYSIBM。 不能将函数名指定为限定名。

XQuery表达式常量

指定一个 SQL 字符串常量，使用受支持的 XQuery 语言语法可将其解释为 XQuery 表达式。 在解析为 XQuery 语句之前，该常量字符串被转换为 UTF-8。 XQuery 表达式使用一组可选的输入 XML 值执行，并返回同样作为 XMLQUERY 表达式的值返回的输出序列。 xquery-expression-constant 的值不能是空字符串或空白字符串 (SQLSTATE 10505)。

PASSING

指定输入值以及这些值传递至 xquery-expression-constant 所指定的 XQuery 表达式的方式。 缺省情况下，通过使用列名作为变量名，将调用函数时所在作用域中的每个唯一列名隐式传递至 XQuery 表达式。 如果指定的 xquery-argument 中的 identifier 与范围内的列名匹配，那么显式 xquery-argument 将传递给覆盖该隐式列的 XQuery 表达式。

BY REF

指定缺省传递机制供数据类型为 XML 的任何 xquery-variable-expression 和返回的值引用。 当通过引用传递 XML 值时，XQuery 求值将直接从指定的输入表达式中使用输入节点树（如果有），这将保留所有属性，包括原始节点标识和文档顺序。 如果两个参数传递相同的 XML 值，并且节点标识比较和文档顺序比较涉及这两个输入参数之间包含的某些节点，那么这两种比较可能引用相同 XML 节点树中的节点。

此子句不影响非 XML 值的传递方式。 非 XML 值在强制转换为 XML 期间将创建值的新副本。

xquery-argument

指定将传递至 xquery-expression-constant 所指定的 XQuery 表达式的参数。 参数指定值和传递该值的方式。 xquery-argument 指定值和传递该值的方式。 在 XQuery 表达式中使用 PASSING 子句中的自变量的方法取决于该自变量已指定为 xquery-context-item-expression 还是 xquery-variable-expression。 xquery-argument 包含一个 SQL 表达式，将对其进行求值，然后将结果传递至 XQuery 表达式。

• 如果生成值的类型是 XML，那么它将变成 input-xml-value。 空 XML 值将转换为 XML 空序列。
• 如果生成值的类型不是 XML，那么它必须可强制转换为 XML 数据类型。 空值将转换为 XML 空序列。 转换后的值将变成 input-xml-value。

对 xquery-expression-constant 进行求值时，将为 XQuery 变量提供一个等于 input-xml-value 的值和由 AS 子句指定的名称。

XQuery上下文项表达式

xquery-context-item-expression 指定 xquery-expression-constant 所指定的 XQuery 表达式中的初始上下文项。 初始上下文项的值是 xquery-context-item-expression 转换为 XML 后的结果。 不得多次指定 xquery-context-item-expression。 xquery-context-item-expression 不得是包含多项的序列。

如果 input-xml-value 是空 XML 字符串，那么将对 XQuery 表达式进行求值，并将初始上下文项设置为空 XML 字符串。 如果 input-xml-value 的值为空，那么函数将返回空值。 如果 xquery-context-item-expression 未指定或者是空序列，那么不会定义 XQuery 表达式中的初始上下文项，并且 XQuery 表达式不得引用初始上下文项。

不会为上下文项表达式创建 XQuery 变量。

XQuery 变量表达式

指定一个 SQL 表达式，其值在执行期间可供 xquery-expression-constant 所指定的 XQuery 表达式使用。 该表达式不能包含序列引用 (SQLSTATE 428F9) 或 OLAP 函数 (SQLSTATE 42903)。 该表达式的数据类型不能是 DECFLOAT。

AS 标识

指定 xquery-variable-expression 所生成的值将作为 XQuery 变量传递至 xquery-expression-constant。 该变量名将为 identifier。 XQuery 语言中的变量名前面的前导美元符号 ($) 不包括在 identifier 中。 标识必须是有效的 XQuery 变量名，并且限于 XML NCName (SQLSTATE 42634)。 标识的长度不能超过 128 个字节。 同一 PASSING 子句中的两个参数不能使用相同的标识 (SQLSTATE 42711)。

BY REF

指示将通过引用传递 XML 输入值。 当通过引用传递 XML 值时，XQuery 求值将直接从指定的输入表达式中使用输入节点树（如果有），这将保留所有属性，包括原始节点标识和文档顺序。 如果两个参数传递相同的 XML 值，并且节点标识比较和文档顺序比较涉及这两个输入参数之间包含的某些节点，那么这两种比较可能引用相同 XML 节点树中的节点。 如果在 xquery-variable-expression 后面未指定 BY REF，那么将使用 PASSING 关键字后面的语法所提供的缺省传递机制传递 XML 参数。 不能对非 XML 值指定此选项。 传递非 XML 值时，该值将转换为 XML；此过程会创建副本。

RETURNING SEQUENCE

指示 XMLQUERY 表达式返回一个序列。

BY REF

指示通过引用返回 XQuery 表达式的结果。 如果此值包含节点，那么使用 XQuery 表达式的返回值的任何表达式将直接接收节点引用，这将保留所有节点属性，包括原始节点标识和文档顺序。 引用的节点在其节点树内保持相连。 如果未指定 BY REF 子句，但指定了 PASSING，那么将使用缺省传递机制。 如果既未指定 BY REF 也未指定 PASSING，那么缺省传递机制为 BY REF。

EMPTY ON EMPTY

指定处理 XQuery 表达式所产生的空序列将作为空序列返回。

结果的数据类型为 XML；它不能为空。

如果对 XQuery 表达式进行求值时产生错误，那么 XMLQUERY 函数将返回 XQuery 错误（SQLSTATE 级别“10”）。