XMLQUERY

The schema is SYSIBM.

xquery-expression-constant

Specifies an SQL character string constant that is interpreted as an XQuery expression using supported XQuery language syntax. For information about the supported XQuery expressions, see XQuery prologs and expressions. xquery-expression-constant cannot be an XQuery updating expression. The XQuery expression is evaluated with the arguments specified in xquery-argument, and returns an output sequence that is also returned as the result of the XMLQUERY function. xquery-expression-constant must not be an empty string or a string of all blanks.

PASSING

Specifies input values and the manner in which these values are passed to the XQuery expression that is specified by xquery-expression-constant.

BY REF

Specifies that the XML input value arguments are to be passed by reference. When XML values are passed by reference, the XQuery evaluation uses the input node trees which preserves all properties, including the original node identities and document order. If two arguments pass the same XML value, node identity comparisons and document ordering comparisons involving some nodes that are contained between the two input arguments might refer to nodes that are within the same XML node tree.

BY REF has no impact on how non-XML values are passed. The non-XML values create a new copy of the value during the cast to XML.

xquery-argument

Specifies an argument that is passed to the XQuery expression that is specified by xquery-expression-constant. A query argument is an expression that returns a value that is XML, integer, decimal, or a character or graphic string that is not a LOB. xquery-argument must not return ROWID, TIMESTAMP, binary string, REAL, DECFLOAT data types, or a character string data type that is bit data, and must not reference a sequence expression.

xquery-argument specifies both a value and the manner in which that value is to be passed. How an argument in the PASSING clause is used in the XQuery expression depends on whether the argument is specified as xquery-context-item-expression or xquery-variable-expression. xquery-argument includes an SQL expression that is evaluated before passing the result to the XQuery expression.

• If the resulting value is of type XML, it becomes an input-xml-value. It is passed by reference, which means that the original values, not copies, are used in the evaluation of the XQuery expression. A null XML value is converted to an XML empty sequence.
• If the resulting value is not of type XML, the result of the expression must be able to be cast to an XML value. A null value is converted to an XML empty sequence. The converted value becomes an input-xml-value.

When xquery-expression-constant is evaluated, an XQuery variable receives a value that is equal to input-xml-value and a name as specified by the AS clause.

xquery-context-item-expression

xquery-context-item-expression specifies the initial context item in the XQuery expression specified by xquery-expression-constant. The value of the initial context item is the result of xquery-context-item-expression cast to XML. xquery-context-item-expression must not be specified more than one time.

xquery-context-item-expression must not be a sequence of more than one item. If input-xml-value is an empty XML string, the XQuery expression is evaluated with the initial context item set to an empty XML string. If the value of input-xml-value is null, the function returns a null value.

If the xquery-context-item-expression is not specified or is an empty sequence, the initial context item in the XQuery expression is undefined and the XQuery expression must not reference the initial context item.

An XQuery variable is not created for the context item expression.

xquery-variable-expression

xquery-variable-expression specifies an SQL expression whose value is available to the XQuery expression that is specified by xquery-expression-constant during execution. The sequence cannot contain a sequence reference.

An XQuery variable is created for each xquery-variable-expression, and the XQuery variable is set to a value equal to input-xml-value. For example, PASSING T.A + T.B AS "sum" creates an XQuery variable named sum. The scope of the XQuery variables that are created from the PASSING clause is the XQuery expression that is specified by xquery-expression-constant.

AS identifier

Specifies that the value that is generated by xquery-variable-expression is passed to xquery-expression-constant as an XQuery variable named identifier. The length of the name must not be longer than 128 bytes. The leading dollar sign ($) that precedes variable names in the XQuery language is not included in identifier. The name must be an XML 1.0 NCName that is not the same as the identifier for another xquery-variable-expression in the same PASSING clause.

RETURNING SEQUENCE

Specifies that the XQuery expression returns a sequence.

BY REF

Specifies that the result of the XQuery expression is returned by reference. If this value contains nodes, any expression that is using the return value of the XQuery expression will receive node references directly, preserving all node properties including the original node identities and document order.

EMPTY ON EMPTY

Specifies that an empty sequence that results from processing the XQuery expression is returned as an empty sequence.

The result of the function is an XML value, and the result can be null. For example, if xquery-context-item-expression is specified and if its value is null, the result of the function is the null value.

If the evaluation of the XQuery expression results in an error, the XMLQUERY function returns the XQuery error.

Let V be the value of the expression. An atomic value of the corresponding XML schema data type is constructed such that the result of cast (V as varchar) is a lexical representation of the constructed atomic value. For example, an SQL VARCHAR value '123' is converted to an atomic value '123' of xs:string type. An SQL integer '12' is converted to an atomic value '12' of xs:integer. An SQL decimal value '1.20' is converted to an atomic value '1.2' of xs:decimal.

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

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

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