>>-XMLQUERY--(--xquery-expression-constant---------------------->
>--+----------------------------------------------+------------->
| .-,-------------------. |
| .-BY REF-. V | |
'-PASSING--+--------+----| xquery-argument |-+-'
.-BY REF-.
.-RETURNING--SEQUENCE--+--------+-. .-EMPTY ON EMPTY-.
>--+---------------------------------+--+----------------+--)--><
xquery-argument
(1)
|--xquery-variable-expression------AS--identifier--+--------+---|
'-BY REF-'
Notes:
- The data type of the expression cannot be DECFLOAT.
The schema is SYSIBM. The function name cannot be specified
as a qualified name.
The XMLQUERY function returns an XML value from the evaluation
of an XQuery expression possibly using specified input arguments as
XQuery variables.
- xquery-expression-constant
- Specifies an SQL character string constant that is interpreted
as an XQuery expression using supported XQuery language syntax. The
constant string is converted to UTF-8 before being parsed as an
XQuery statement. The XQuery expression executes using an optional
set of input XML values, and returns an output sequence that is also
returned as the value of the XMLQUERY expression. The value for xquery-expression-constant must
not be an empty string or a string of blank characters (SQLSTATE 10505).
- PASSING
- Specifies input values and the manner in which these values are
passed to the XQuery expression specified by xquery-expression-constant.
By default, every unique column name that is in the scope where the
function is invoked is implicitly passed to the XQuery expression
using the name of the column as the variable name. If an identifier in
a specified xquery-argument matches an in-scope column name, then
the explicit xquery-argument is passed to the XQuery expression overriding
that implicit column.
- BY REF
- Specifies that the default passing mechanism is by reference
for any xquery-variable-expression of data
type XML and for the returned value. When XML values are passed
by reference, the XQuery evaluation uses the input node trees, if
any, directly from the specified input expressions, preserving 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 contained between
the two input arguments might refer to nodes within the same XML node
tree.
This clause 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 to be passed to the XQuery expression
specified by xquery-expression-constant.
An argument specifies a value and the manner in which that value is
to be passed. The argument includes an SQL expression that is evaluated.
- If the resulting value is of type XML, it becomes an input-xml-value.
A null XML value is converted to an XML empty sequence.
- If the resulting value is not of type XML, it must be castable
to the XML data type. A null value is converted to an XML empty sequence.
The converted value becomes an input-xml-value.
When the xquery-expression-constant is
evaluated, an XQuery variable is presented with a value equal to input-xml-value and
a name specified by the AS clause. - xquery-variable-expression
- Specifies an SQL expression whose value is available to the XQuery
expression specified by xquery-expression-constant during
execution. The expression cannot contain a sequence reference (SQLSTATE
428F9) or an OLAP function (SQLSTATE 42903). The data type of
the expression cannot be DECFLOAT.
- AS identifier
- Specifies that the value generated by xquery-variable-expression will
be passed to xquery-expression-constant as
an XQuery variable. The variable name will be identifier.
The leading dollar sign ($) that precedes variable names in the XQuery
language is not included in identifier.
The identifier must be a valid XQuery variable name and is restricted
to an XML NCName (SQLSTATE 42634). The identifier must not
be greater than 128 bytes in length. Two arguments within the same
PASSING clause cannot use the same identifier (SQLSTATE 42711).
- BY REF
- Indicates that an XML input value is to be passed by reference.
When XML values are passed by reference, the XQuery evaluation uses
the input node trees, if any, directly from the specified input expressions,
preserving 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 contained between the two input arguments might refer to nodes
within the same XML node tree. If BY REF is not specified following
an xquery-variable-expression, XML arguments
are passed by way of the default passing mechanism that is provided
through the syntax that follows the PASSING keyword. This option cannot
be specified for non-XML values. When a non-XML value is passed, the
value is converted to XML; this process creates a copy.
- RETURNING SEQUENCE
- Indicates that the XMLQUERY expression returns a sequence.
- BY REF
- Indicates that the result of the XQuery expression is returned
by reference. If this value contains nodes, any expression 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. Referenced nodes will remain connected
within their node trees. If the BY REF clause is not specified and
the PASSING is specified, the default passing mechanism is used. If
BY REF is not specified and PASSING is not specified, the default
returning mechanism is BY REF.
- EMPTY ON EMPTY
- Specifies that an empty sequence result from processing the XQuery
expression is returned as an empty sequence.
The data type of the result is XML; it cannot be null.
If the evaluation of the XQuery expression results in
an error, then the XMLQUERY function returns the XQuery error (SQLSTATE
class '10').
Note: - XMLQUERY usage restrictions: The XMLQUERY function cannot
be:
- Part of the ON clause that is associated with a JOIN operator
or a MERGE statement (SQLSTATE 42972)
- Part of the GENERATE KEY USING or RANGE THROUGH clause in the
CREATE INDEX EXTENSION statement (SQLSTATE 428E3)
- Part of the FILTER USING clause in the CREATE FUNCTION (External
Scalar) statement, or the FILTER USING clause in the CREATE INDEX
EXTENSION statement (SQLSTATE 428E4)
- Part of a check constraint or a column generation expression (SQLSTATE
42621)
- Part of a group-by-clause (SQLSTATE 42822)
- Part of an argument for a column-function (SQLSTATE 42607)
- XMLQUERY as a subquery: An XMLQUERY expression that acts
as a subquery can be restricted by statements that restrict subqueries.