Función escalar XMLQUERY

El esquema es SYSIBM. El nombre de la función no puede especificarse como un nombre calificado.

constante-expresión-xquery

Especifica una constante de serie de caracteres de SQL que se interpreta como una expresión XQuery mediante la sintaxis del lenguaje XQuery soportada. La serie de la constante se convierte a UTF-8 antes de analizarse como sentencia XQuery. La expresión XQuery se ejecuta utilizando un conjunto opcional de valores XML de entrada y devuelve una secuencia de salida que también se devuelve como valor de la expresión XMLQUERY. El valor para la constante-expresión-xquery no debe ser una serie vacía o una serie de caracteres en blanco (SQLSTATE 10505).

PASSING

Especifica los valores de entrada y el modo en que pasan a la expresión XQuery especificada por la constante-expresión-xquery. Por omisión, cada nombre de columna exclusivo en el ámbito en el que se invoca la función se pasa implícitamente a la expresión XQuery utilizando el nombre de la columna como nombre de variable. Si un identificador de un argumento-xquery especificado coincide con el nombre de columna con ámbito, entonces el argumento-xquery explícito se pasa a la expresión XQuery alterando temporalmente dicha columna implícita.

BY REF

Especifica que el mecanismo de pase por omisión es por referencia para cualquier expresión-variable-xquery de tipo de datos XML y para el valor devuelto. Cuando los valores XML se pasan por referencia, la evaluación de XQuery utiliza los árboles de nodos de entrada, si los hay, directamente desde las expresiones de entrada especificadas, con lo que se conservan todas las propiedades, incluyendo las identidades de nodo originales y el orden del documento. Si dos argumentos pasan el mismo valor XML, las comparaciones de identidad de nodo y orden de documento en que intervienen algunos nodos incluidos entre los dos argumentos de entrada pueden hacer referencia a nodos del mismo árbol de nodos XML.

Esta cláusula no afectará al modo en que se pasan los valores que no son XML. Los valores que no son XML crean una copia nueva del valor durante la conversión a XML.

argumento-xquery

Especifica un argumento que se pasará a la expresión XQuery especificada por constante-expresión-xquery. Un argumento especifica un valor y la forma en que ese valor se debe pasar. El argumento-xquery especifica un valor y la forma en que ese valor se debe pasar. El método con que se utiliza un argumento, de la cláusula PASSING, en la expresión XQuery depende de si se especifica el argumento como expresión-elemento-contexto-xquery o expresión-variable-xquery. El argumento-xquery incluye una expresión SQL que se evalúa antes de que pase el resultado a la expresión XQuery.

• Si el valor del resultado es del tipo XML, pasa a ser un valor-xml-entrada. Un valor XML nulo se convierte en una secuencia XML vacía.
• Si el valor del resultado no es del tipo XML, debe ser convertible al tipo de datos XML. Un valor nulo se convierte en una secuencia XML vacía. El valor convertido se transforma en un valor-xml-entrada.

Cuando se evalúa la constante-expresión-xquery, se presenta un valor igual a valor-xml-entrada a una variable XQuery y la cláusula AS especifica un nombre.

expresión-elemento-contexto-xquery

La expresión-elemento-contexto-xquery especifica el elemento de contexto inicial de la expresión XQuery inicial especificada mediante la constante-expresión-xquery. El valor del elemento de contexto inicial es el resultado de la expresión-elemento-contexto-xquery en XML. La expresión-elemento-contexto-xquery no se debe especificar más de una vez. La expresión-elemento-contexto-xquery no debe ser una secuencia de más de un elemento.

Si el valor-xml-entrada es una serie XML vacía, la expresión XQuery se evalúa con el elemento de contexto inicial establecido en una serie XML vacía. Si el valor-xml-entrada es nulo, se devuelve un valor nulo. Si la expresión-elemento-contexto-xquery no se especifica o si es una secuencia vacía, el elemento de contexto inicial de la expresión XQuery no se define, y la expresión XQuery no debe hacer referencial al elemento de contexto inicial.

No se crea una variable XQuery para la expresión de elemento de contexto.

expresión-variable-xquery

Especifica una expresión SQL cuyo valor está disponible para la expresión XQuery especificada por constante-expresión-xquery durante la ejecución. La expresión no puede contener una referencia de secuencia (SQLSTATE 428F9) ni una función OLAP (SQLSTATE 42903). El tipo de datos de la expresión no puede ser DECFLOAT.

AS identificador

Especifica que el valor generado por expresión-variable-xquery se pasará a constante-expresión-xquery como una variable XQuery. El nombre de la variable será identificador. El signo de dólar inicial ($) que precede a los nombres de variable en el lenguaje XQuery no se incluye en el identificador. El identificador debe ser un nombre de variable XQuery válido y debe tener el formato de un nombre XML NCName (SQLSTATE 42634). El identificador no debe tener más de 128 bytes de longitud. Dos argumentos de la misma cláusula PASSING no pueden emplear el mismo identificador (SQLSTATE 42711).

BY REF

Indica que un valor de entrada XML se debe pasar por referencia. Cuando los valores XML se pasan por referencia, la evaluación de XQuery utiliza los árboles de nodos de entrada, si los hay, directamente desde las expresiones de entrada especificadas, con lo que se conservan todas las propiedades, incluyendo las identidades de nodo originales y el orden del documento. Si dos argumentos pasan el mismo valor XML, las comparaciones de identidad de nodo y orden de documento en que intervienen algunos nodos incluidos entre los dos argumentos de entrada pueden hacer referencia a nodos del mismo árbol de nodos XML. Si no se especifica BY REF a continuación de una expresión-variable-xquery, los argumentos XML se pasan mediante el mecanismo de pase por omisión que se proporciona mediante la sintaxis situada tras la palabra clave PASSING. Esta opción no puede especificarse para valores que no son XML. Cuando se pasa un valor que no es XML, el valor se convierte a XML; este proceso crea una copia.

RETURNING SEQUENCE

Indica que la expresión XMLQUERY devuelve una secuencia.

BY REF

Indica que el resultado de la expresión XQuery se devuelve por referencia. Si este valor contiene nodos, toda expresión que utilice el valor de retorno de la expresión XQuery recibirá directamente las referencias de nodo, con lo que se conservan todas las propiedades de los nodos, como las identidades de nodo originales y el orden del documento. Los nodos a los que se haga referencia seguirán conectados dentro de sus árboles de nodos. Si no se especifica la cláusula BY REF y se especifica PASSING, se utiliza el mecanismo de pase por omisión. Si no se especifica BY REF y no se especifica PASSING, el mecanismo de retorno por omisión es BY REF.

EMPTY ON EMPTY

Especifica un resultado de secuencia vacía obtenido del proceso de la expresión XQuery se devuelve como una secuencia vacía.

El tipo de datos del resultado es XML; no puede ser nulo.

Si la evaluación de la expresión XQuery genera un error, la función XMLQUERY devuelve el error de XQuery (clase de SQLSTATE '10').