XMLMODIFY スカラー関数

XMLMODIFY 関数は、入力引数として指定されている XQuery 更新式および XQuery 変数の評価によって変更された可能性がある XML 値を戻します。

スキーマは SYSIBM です。

xquery-update-constant

サポートされている XQuery 言語構文を使用する XQuery 更新式として解釈されるSQL文字列定数を指定します。 xquery-update-constant は、以下のいずれかの項目にする必要があります。

挿入式。
削除式。
置換式。
return 節に更新式を含む FLWOR 式。
then 節または else 節に更新式を含む条件式。
2 つ以上のコンマ区切りの更新式を含むシーケンス式。すべてのオペランドは更新式または空シーケンスのいずれかです。

xquery-update-constant に、空ストリングまたはすべてがブランクのストリングを指定してはいけません。

xquery-variable-expression

xquery-variable-expression は、実行中に xquery-update-constant によって指定される XQuery 式で使用可能な値を持つ SQL 式を指定します。

xquery-variable-expression のデータ・タイプは、XML、整数、10 進数、または LOB 以外の文字ストリングまたはグラフィック・ストリングです。 xquery-variable-expression は、ROWID、TIMESTAMP、バイナリー・ストリング、REAL、DECFLOAT の各データ・タイプ、またはビット・データである文字ストリングを戻してはなりません。また、xquery-variable-expression は、シーケンス式を参照してはなりません。結果値がXML型の場合、参照渡しが行われ、 XQuery 式の評価にはコピーではなく元の値が使用されることを意味します。 NULL の XML 値は、XML の空シーケンスに変換されます。結果の値がタイプ XML でない場合、式の結果を XML 値にキャスト可能でなければなりません。 NULL 値は、XML の空シーケンスに変換されます。非 XML 値は、XML へのキャスト中にその値の新しいコピーを作成します。

これが指定される xquery-variable-expression ごとに XQuery 変数が作成され、XQuery 変数は input-xml-value と等しい値に設定されます。

AS 識別子

xquery-variable-expression によって生成された値が、 XQuery という識別子を持つ変数として xquery-update-constant に渡されることを指定します。名前の長さは、128 バイトを超えてはいけません。名前の長さが 128 バイトより長い場合、エラーが戻されます。 XQuery 言語では、変数名の先頭に置かれるドル記号（$）は識別子には含まれません。名前は、同じ PASSING 文節内の別の xquery-variable-expression の ID と同じでない、XML 1.0 NCName でなければなりません。 ID が XML 1.0 NCName でない場合、エラーが戻されます。複数の xquery-variable-expression が同じ名前を持っている場合、エラーが戻されます。 xquery-variable式の結果がnullの場合、対応する XQuery 変数には空のシーケンスが代入されます。

XMLMODIFY 関数は、SQL UPDATE ステートメント内、または SQL MERGE ステートメントの更新節内でのみ使用できます。 XMLMODIFY 関数は、更新の SET 代入節の右側の最上位式である必要があります。

XMLMODIFY 呼び出し内では、更新式は他の更新式によって追加される新しいノードを変更できません。例えば、更新式で新しいエレメント・ノードを追加する場合、別の更新式では新しく作成されたそのノードを変更することはできません。

XMLMODIFYの呼び出しの場合、 Db2 データベースマネージャーは、以下の順序で更新式を適用します

非 deterministic 順序における、次の操作
- before、after、as first、as last などの順序付けキーワードを使用していない挿入操作。
- キーワード value of が指定されていて、かつターゲット・ノードが属性ノード、テキスト・ノード、または処理命令ノードである置換操作。
before、after、as first、as last などの順序付けキーワードを使用している挿入操作。
キーワード value of が指定されていない置換操作。
キーワード value of が指定されていて、かつターゲット・ノードがエレメント・ノードである置換操作。
すべての削除操作。

target-xml-column は、XMLMODIFY 関数によって戻される値で更新される、SET 代入節内の XML 列です。 XQuery 更新式における最初のコンテキスト項目は、参照渡しされる target-xml-columnの値です。 XQuery 更新式で変更できるのは、target-xml-columnの値のみです。つまり、 XQuery の更新式のターゲット式ノードは、target-xml-columnの値のノードでなければなりません。 target-xml-column は、XML バージョン管理フォーマットで定義される XML 列である必要があります。

XQuery 更新式によって変更される target-xml-column の値は、関数によって返されます。 target-xml-column の値が NULL の場合、関数は NULL を戻します。それ以外の場合、XMLMODIFY 関数の結果は整形式 XML 文書である必要があります。 XQuery の更新式がtarget-xml-columnの値に変更を加えない場合、変更されていないXML値が関数によって返されます。 XMLMODIFY 関数は、target-xml-column の元のノード ID と文書の順序を保存します。 XMLMODIFY は、SQL UPDATE ステートメントで更新される行ごとに、参照によって target-xml-column を変更しますが、SQL UPDATE ステートメント内での target-xml-column の参照は、行が更新される前の target-xml-column の値になります。

例1： 以下は、 XQuery の挿入式を持つXMLMODIFY関数の例です。表に、XML 文書「purchaseOrders」を含む PO という名前の列が含まれているとします。

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 に、以下の XML 文書を含む PORDER という名前の列が含まれているとします。

<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>

以下は、 XQuery の置換式と XQuery の削除式を使用したXMLMODIFY関数の例です。

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>