XMLMODIFY 标量函数 (scalar function)

XMLMODIFY函数返回一个XML值，该值可能已被 XQuery 更新表达式和 XQuery 变量的计算修改，这些变量被指定为输入参数。

阅读语法图跳过可视化语法图XMLMODIFY(XQuery更新常量 ,,XQuery 变量表达式AS标识 )

该模式是 SYSIBM。

XQuery更新常量
更改开始指定一个SQL字符串常量，该常量被解释为使用支持的 XQuery 语言语法的 XQuery 更新表达式。 xquery-update-constant 必须为以下选项之一：
  • 插入表达式。
  • 删除表达式。
  • 替换表达式。
  • 一个FLWOR表达式，其返回子句中包含一个更新表达式。
  • 一个条件表达式，其then或else子句中包含一个更新表达式。
  • 包含两个或多个更新表达式的序列表达式，以逗号分隔。 所有操作数要么是更新表达式，要么是空序列。

xquery-update-constant 不能为空字符串或全空字符串。

更改结束
XQuery变量表达式
xquery-variable-expression 指定一个 SQL 表达式，其值在执行期间可用于 xquery-update-constant 指定的 XQuery 表达式。

xquery-variable-expression 的数据类型可以是XML、整数、小数或非LOB的字符串或图形字符串。 xquery-variable-expression 不能返回 ROWID、TIMESTAMP、二进制字符串、REAL、DECFLOAT 数据类型或作为位数据的字符串，并且 xquery-variable-expression 不能引用序列表达式。 如果结果值为XML类型，则通过引用传递，这意味着在 XQuery 表达式的计算中使用的将是原始值，而非副本。 空 XML 值将转换为 XML 空序列。 如果结果值不是XML类型，则表达式的结果必须转换为XML值。 空值将转换为 XML 空序列。 在转换为XML时，非XML值会创建一个新的值副本。

为每个指定的xquery-variable-expression 创建一个 XQuery 变量，并将 XQuery 变量设置为等于input-xml-value 的值。

AS 识别码
指定将xquery-variable-expression 生成的值作为名为identifier的 XQuery 变量传递给 xquery-update-constant。 名字的长度不能超过128个字节。 如果名称长度超过128字节，则返回错误。 XQuery 语言中变量名称前面的美元符号（$）不包含在标识符中。 名称必须是一个XML 1.0 NCName，且与同一PASSING子句中其他xquery变量表达式的标识符不同。 如果标识符不是XML 1.0 NCName，则返回错误。 如果多个 xquery变量表达式具有相同的名称，则返回错误。 如果 xquery变量表达式的结果为空，则会将空序列赋给相应的 XQuery 变量。

XMLMODIFY函数只能在SQL UPDATE语句或SQL MERGE语句的更新子句中使用。 XMLMODIFY函数必须是更新SET赋值子句右侧最上层的表达式。

更改开始在XMLMODIFY调用中，更新表达式不能修改其他更新表达式添加的新节点。 例如，如果一个更新表达式添加了一个新的元素节点，另一个更新表达式不能更改新创建的节点。更改结束

更改开始对于XMLMODIFY调用， Db2 数据库管理器按以下顺序应用更新表达式：更改结束

  1. 更改开始以下操作，顺序不确定：
    • 插入不使用排序关键字的操作，例如 before 、after 、as first 或 as last
    • 替换操作中指定了关键字值 ，且目标节点是属性节点、文本节点、注释节点或处理指令节点
    更改结束
  2. 插入使用排序关键字的操作，例如 “之前 ”、“之后 ”、“作为第一 ”或 “作为最后 ”
  3. 替换未指定关键字值的操作
  4. 替换指定关键字值为的操作，目标节点为元素节点
  5. 所有删除操作

目标XML列是SET赋值子句中的XML列，该列将由XMLMODIFY函数返回的值更新。 XQuery 更新表达式中的初始上下文项是通过引用传递的目标-xml-列的值。 只有目标-xml-列的值可以通过 XQuery 更新表达式进行修改。 换句话说， XQuery 更新表达式中的目标表达式节点必须是 target-xml-column 值中的一个节点。 目标-xml-列必须是以XML版本控制格式定义的XML列。

函数返回由 XQuery 更新表达式修改的目标-xml-列的值。 如果目标XML列的值为空，则函数返回空。 否则，XMLMODIFY函数的结果必须是一个格式正确的XML文档。 如果 XQuery 更新表达式不对 target-xml-column的值进行修改，则函数将返回未修改的XML值。 XMLMODIFY函数保留目标xml列的原始节点标识和文档顺序。 虽然XMLMODIFY通过引用修改 target-xml-column ，但对于SQL UPDATE语句更新的每一行，SQL UPDATE语句中对target-xml-column的任何引用都是该行更新前的 target-xml-column的值。

示例1： 以下是一个带有 XQuery 插入表达式的XMLMODIFY函数示例。 假设一个表中有一个名为PO的列，其中包含一个XML文档， 'purchaseOrders':
UPDATE purchaseOrders
   SET PO = XMLMODIFY('declare namespace ipo="http://www.example.com/IPO";
                       declare namespace pyd="http://www.examplepayment.com";
                       insert node $payment/@pyd:paidDate 
                         as first into /ipo:purchaseOrder/billTo', 
                       XMLPARSE(DOCUMENT 
												'<payment xmlns:pyd="http://www.examplepayment.com"
                                    pyd:paidDate="2000-01-07">278.94
												 </payment>') AS "payment")
PO列中 purchaseOrders XML文档的结果如下：
<ipo:purchaseOrder
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:ipo="http://www.example.com/IPO"
  xmlns:pyd="http://www.examplepayment.com"
  orderDate="1999-12-01" pyd:paidDate="2000-01-07">

<shipTo exportCode="1" xsi:type="ipo:UKAddress">
<name>Helen Zoe</name>
      <street>47 Eden Street</street>
      <city>Cambridge</city>
      <postcode>CB1 1JR</postcode>
  </shipTo>
  .
  .
  .
 </ipo:purchaseOrder>
更改开始示例2 ：假设表PURCHASEORDER包含一个名为PORDER的列，其中包含以下XML文档：
<ipo:purchaseOrder
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:ipo="http://www.example.com/IPO"
 xmlns:pyd="http://www.examplepayment.com"
 orderDate="1999-12-01" pyd:paidDate="2000-01-07">
 <shipTo exportCode="1" xsi:type="ipo:UKAddress">
  <name>Helen Zoe</name>
  <street>47 Eden Street</street>
  <city>Cambridge</city>
  <postcode>CB1 1JR</postcode>
 </shipTo>
 <items>
  <item partNum="872-AA">
   <productName>Lawnmower</productName>
   <quantity>1</quantity>
   <USPrice>149.99</USPrice>
   <shipDate>2011-05-20</shipDate>
  </item>
  <item partNum="945-ZG">
   <productName>Sapphire Bracelet</productName>
   <quantity>2</quantity>
   <USPrice>178.99</USPrice>
   <comment>Not shipped</comment>
  </item>
 </items>
</ipo:purchaseOrder>
以下是一个XMLMODIFY函数的示例，其中包含一个 XQuery 替换表达式和一个 XQuery 删除表达式。
UPDATE PURCHASEORDER
 SET PORDER = XMLMODIFY(
 'declare namespace ipo="http://www.example.com/IPO";
  replace value of node /ipo:purchaseOrder/items/item[@partNum="872-AA"]/quantity
  with xs:integer(2),
  delete node /ipo:purchaseOrder/items/item[@partNum="945-ZG"]’);
UPDATE语句执行后，结果如下：更改结束
更改开始
<ipo:purchaseOrder
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:ipo="http://www.example.com/IPO"
 xmlns:pyd="http://www.examplepayment.com"
 orderDate="1999-12-01" pyd:paidDate="2000-01-07">
 <shipTo exportCode="1" xsi:type="ipo:UKAddress">
  <name>Helen Zoe</name>
  <street>47 Eden Street</street>
  <city>Cambridge</city>
  <postcode>CB1 1JR</postcode>
 </shipTo>
 <items>
  <item partNum="872-AA">
   <productName>Lawnmower</productName>
   <quantity>2</quantity>
   <USPrice>149.99</USPrice>
   <shipDate>2011-05-20</shipDate>
  </item>
</items>
</ipo:purchaseOrder>
更改结束