Transform expression

A transform expression creates copies of one or more nodes. Updating expressions in the modify clause of the transform expression change the copied nodes. The expression in the return clause specifies the result of the transform expression.

Syntax

copy clause

modify clause

return clause

Parameters

transform

Optional keyword that can be used to begin a transform expression.

copy

Keyword that begins the copy clause of a transform expression. Each VariableName in the copy clause is bound to a logical copy of the node tree that is returned by the corresponding CopySourceExpression.

VariableName

The name of the variable to bind to a copy of the node tree returned by CopySourceExpression.

CopySourceExpression

An XQuery expression that is not an updating expression. The expression must return a single node, together with its descendants (if any), called a node tree.

If the expression includes a top-level comma operator, the expression must be enclosed in parentheses. The CopySourceExpression is evaluated as though it were an enclosed expression in an element constructor.

The nodes created by the copy clause have new node identities and are untyped.

modify

Keyword that begins the modify clause of a transform expression.

ModifyExpression

An updating expression or an empty sequence. If the expression includes a top-level comma operator, the expression must be enclosed in parentheses. The updating expression is evaluated and the resulting updates are applied to nodes created by the copy clause.

Db2 XQuery returns an error if the target node of an updating expression is not a node created by the copy clause of the containing transform expression. For example, Db2 XQuery returns an error if a rename expression tries to rename a node that is not created by the copy clause.

The updates specified in a modify clause can result in a node that has multiple, adjacent text nodes among its children. If a node has multiple, adjacent text nodes among its children, the adjacent text nodes are merged into a single text node. The string value of the resulting text node is the concatenated string values of the adjacent text nodes with no intervening spaces. If a child node is created that is a text node with a string value that is a zero-length string, the text node is deleted.

return

The keyword that begins the return clause of a transform expression.

ReturnExpression

An XQuery expression that is not an updating expression. If the expression includes a top-level comma operator, the expression must be enclosed in parentheses.

The expression in the return clause is evaluated and is returned as the result of the transform expression. Expressions in the return clause can access the nodes changed or created by updating expressions in the modify clause.

The return clause of a transform expression is not restricted to return only nodes that were created by the copy clause. The ReturnExpression can return any combination of copied nodes, original nodes, and constructed nodes.

Examples

The following examples use the CUSTOMER table from the Db2 SAMPLE database. In the CUSTOMER table, the XML column INFO contains customer address and phone information.

In the following example, the copy clause of the transform expression creates a copy of the XML document from the column INFO. In the modify clause, the delete expression deletes all phone numbers from the XML document where the phone's type attribute is not home:

xquery 
transform 
   copy $mycust := db2-fn:sqlquery('select INFO from CUSTOMER where Cid = 1003') 
   modify 
     do delete $mycust/customerinfo/phone[@type!="home"]
   return $mycust;

When run against the SAMPLE database, the expression returns the following result:

<customerinfo Cid="1003">
  <name>Robert Shoemaker</name>
  <addr country="Canada">
    <street>1596 Baseline</street>
    <city>Aurora</city>
    <prov-state>Ontario</prov-state>
    <pcode-zip>N8X 7F8</pcode-zip>
  </addr>
  <phone type="home">416-555-2937</phone>
</customerinfo>

The following expression does not use the optional keyword transform. The transform expression starts with the copy clause and is equivalent to the previous expression.

xquery 
copy $mycust := db2-fn:sqlquery('select INFO from CUSTOMER where Cid = 1003') 
modify 
   do delete $mycust/customerinfo/phone[@type!="home"]
return $mycust;

In the following example, the SQL UPDATE statement modifies and validates the XML document from a row of the CUSTOMER table. The copy clause of the transform expression creates a copy of the XML document from the column INFO. The replace expression changes the value of the name element in the copy of the XML document. The copy of the document is not validated. The XMLVALIDATE function validates the document copy:

UPDATE customer set info = XMLVALIDATE(
  XMLQUERY('transform
  copy $mycust := $cust
  modify 
    do replace value of $mycust/customerinfo/name with "Larry Menard, Jr."
  return $mycust'
  passing info as "cust" )
ACCORDING TO XMLSCHEMA ID customer)
where cid = 1005