XMLQUERY 标量函数 (scalar function)

XMLQUERY函数通过指定输入参数、上下文项和 XQuery 变量，从 XQuery 表达式的计算结果中返回一个XML值。

注意：

¹ xquery-context-item-expression 不能指定多次。

xquery-argument:

该模式是 SYSIBM。

XQuery表达式常量

指定一个SQL字符串常量，该常量使用支持的 XQuery 语言语法解释为 XQuery 表达式。有关支持的 XQuery 表达式，请参阅 XQuery前缀和表达式。 xquery-expression-constant 不能是 XQuery 更新表达式。 XQuery 表达式使用xquery-argument中指定的参数进行评估，并返回一个输出序列，该输出序列也作为XMLQUERY函数的结果返回。 xquery-expression-constant 不能为空字符串或全空字符串。

PASSING

指定输入值以及将这些值传递给由xquery-expression-constant 指定的 XQuery 表达式的方式。

BY REF

指定以引用方式传递XML输入值参数。当通过引用传递 XML 值时， XQuery 评估使用输入节点树，该树保留所有属性，包括原始节点标识和文档顺序。如果两个参数传递相同的XML值，涉及两个输入参数之间包含的某些节点的节点标识比较和文档排序比较可能会引用同一XML节点树中的节点。

BY REF对非XML值的传递方式没有影响。非 XML 值在强制转换为 XML 期间将创建值的新副本。

XQuery参数

指定传递给由xquery-expression-constant 指定的 XQuery 表达式的参数。查询参数是一个表达式，返回的值可以是XML、整数、小数或非LOB字符或图形字符串。 xquery-argument 不能返回 ROWID、TIMESTAMP、二进制字符串、REAL、DECFLOAT 数据类型或包含位数据的字符串数据类型，也不能引用序列表达式。

xquery-argument 指定一个值以及传递该值的方式。 XQuery 表达式中PASSING子句中的参数如何使用取决于参数是作为 xquery-context-item-expression 还是 xquery-variable-expression。 xquery-argument 包含一个SQL表达式，在将结果传递给 XQuery 表达式之前，先对SQL表达式进行计算。

如果生成值的类型是 XML，那么它将变成 input-xml-value。它通过引用传递，这意味着在评估 XQuery 表达式时使用的是原始值，而不是副本。空 XML 值将转换为 XML 空序列。
如果结果值不是XML类型，则表达式的结果必须能够转换为XML值。空值将转换为 XML 空序列。转换后的值将变成 input-xml-value。

当 xquery-expression-constant 被计算时，一个 XQuery 变量接收一个等于 input-xml-value 的值和一个由AS子句指定的名称。

xquery-context-item-expression

xquery-context-item-expression 指定了由 xquery-expression-constant 指定的 XQuery 表达式中的初始上下文项。初始上下文项的值是 xquery-context-item-expression 转换为XML的结果。 xquery-context-item-expression 不能指定多次。

xquery-context-item-expression 不能是一个以上的项目序列。如果输入的xml值是一个空的XML字符串，则 XQuery 表达式的初始上下文项设置为空的XML字符串。如果输入的xml-value 值为空，则函数返回空值。

如果未指定 xquery-context-item-expression 或该表达式为空序列，则 XQuery 表达式中的初始上下文项未定义，且 XQuery 表达式不得引用初始上下文项。

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

xquery-variable-expression

xquery-variable-expression 指定一个 SQL 表达式，其值在执行期间可用于 xquery-expression-constant 指定的 XQuery 表达式。序列中不能包含序列引用。

为每个 xquery-variable-expression 创建一个 XQuery 变量，并将 XQuery 变量设置为等于 input-xml-value 的值。例如， PASSING T.A + T.B AS "sum" 创建了一个名为sum的 XQuery 变量。由PASSING子句创建的 XQuery 变量的范围是 xquery-expression-constant 指定的 XQuery 表达式。

AS 标识符

指定将xquery-variable-expression 生成的值作为名为identifier的 XQuery 变量传递给 xquery-expression-constant。名字的长度不能超过128个字节。 XQuery 语言中变量名称前面的美元符号（$）不包含在标识符中。名称必须是一个XML 1.0 NCName，且与同一PASSING子句中其他xquery变量表达式的标识符不同。

RETURNING SEQUENCE

指定 XQuery 表达式返回一个序列。

BY REF

指定 XQuery 表达式的结果通过引用返回。如果该值包含节点，则任何使用 XQuery 表达式的返回值的表达式将直接接收节点引用，并保留所有节点属性，包括原始节点标识和文档顺序。

EMPTY ON EMPTY

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

更改开始函数的计算结果是一个XML值，结果可以为空。例如，如果指定了 xquery-context-item-expression ，且其值为空，则函数的返回值为空。更改结束

如果对 XQuery 表达式的评估出现错误，则XMLQUERY函数将返回XQuery错误。

注意

将非XML值隐式转换为XML值：

如果 xquery-argument 的结果不是XML类型，则按如下方式将该值转换为XML。根据下表，表达式的SQL数据类型映射到相应的XML Schema数据类型：

表 1. SQL数据类型和相应的XML模式数据类型
SQL 数据类型	XML 模式数据类型
CHAR 或 VARCHAR	xs:string
图形、VAR图形	xs:string
SMALLINT	xs:integer
INTEGER	xs:integer
BIGINT	xs:integer
DECIMAL	xs:decimal
双	xs:double
FLOAT	xs:double

设 V 为表达式的值。构造相应XML模式数据类型的原子值，使得 cast (V as varchar) 的结果是构造原子值的词法表示。例如，SQL VARCHAR值“123”将转换为xs:string类型的原子值“123”。 SQL整数“12”转换为xs:integer的原子值“12”。 SQL十进制值“ 1.20 ”转换为xs:decimal的原子值“ 1.2 ”。

示例

示例 1：

以下示例通过评估指定的 XQuery 表达式返回一个XML值：

  SELECT XMLQUERY('//item[productName=$n]'
                  PASSING PO.POrder,
                  :hv AS "n") AS "Result"
     FROM PurchaseOrders PO;

假设宿主变量hv 的值为“婴儿监视器”，结果与以下结果类似：

Result
-------------------------------------------------------------------------

<item partNum="926-AA"><productName>Baby Monitor</productName><quantity>1
</quantity><USPrice>39.98</USPrice><shipDate>1999-05-21</shipDate></item>