XMLELEMENT función escalar

La función XMLELEMENT devuelve un valor XML que es un nodo de elemento XML.

Notas:

¹ La cláusula OPTION solo puede especificarse si se especifica al menos una xmlattributes-function o una element-content-expression
² Si no se especifica element-content-expression, no se deben especificar EMPTY ON NULL y NULL ON NULL.
³ La misma cláusula no debe especificarse más de una vez.

El esquema es SYSIBM.

NOMBRE elemento-nombre

Especifica el nombre de un elemento XML. element-name es un identificador SQL que debe tener la forma de un nombre calificado XML o QName. Si el nombre está calificado, el prefijo del espacio de nombres debe declararse dentro del ámbito.

declaración-xmlnamespaces

Especifica las declaraciones de espacio de nombres XML que son el resultado de la función XMLNAMESPACES. Los espacios de nombres que se declaran se encuentran en el ámbito de la función XMLELEMENT. Los nombres de espacios se aplican a cualquiera de las funciones XML anidadas que se encuentran dentro de la función XMLELEMENT, con independencia de si aparecen o no dentro de otra subselección. Consulte la función escalar XMLNAMESPACES para obtener más información sobre la declaración de espacios de nombres XML.

Si no se especifica xmlnamespaces-declaration, las declaraciones de espacio de nombres no se asocian con el nodo de elemento XML construido.

función-xmlattributes

Especifica los atributos para el elemento XML. Los atributos son el resultado de la función XMLATTRIBUTES. Consulte la función escalar XMLATTRIBUTES para obtener más información sobre la construcción de atributos.

Si no se especifica xmlattributes-function, los atributos no forman parte explícitamente del nodo del elemento XML construido.

expresión-contenido-elemento

El contenido del nodo de elemento XML generado se especifica mediante una expresión o una lista de expresiones. Cada elemento-contenido-expresión debe devolver un valor de cualquier tipo de datos incorporado o tipo distinto. La expresión se utiliza para construir las declaraciones de espacio de nombres, los atributos y el contenido del nodo del elemento construido.

Si no se especifica element-content-expression, se utiliza una cadena vacía como contenido para el elemento y no se debe especificar NULL ON NULL o EMPTY ON NULL.

opción

Especifica opciones adicionales para construir el elemento XML. Esta cláusula no tiene ningún impacto en las invocaciones anidadas de las invocaciones de la función XMLELEMENT que se especifican en element-content-expression.

EMPTY ON NULL o NULL ON NULL

Especifica si se devuelve un valor nulo o un elemento vacío cuando los valores de cada expresión-contenido-elemento son un valor nulo. Esta opción sólo afecta al manejo de nulos del contenido del elemento, no a los valores de atributo. La opción no se hereda mediante una invocación anidada de la función XMLELEMENT dentro de una expresión de contenido de elemento.

EMPTY ON NULL: Si el valor de cada expresión-contenido-elemento es nulo, se devuelve un elemento vacío.
EMPTY ON NULL es el valor predeterminado.
NULL ON NULL: Si el valor de cada elemento expresión-contenido-elemento es nulo, se devuelve un valor nulo.

XMLBINARY USING BASE64 o XMLBINARY USING HEX

Especifica la codificación asumida de los datos de entrada binarios, los datos de cadena de caracteres con el atributo FOR BIT DATA, ROWID o un tipo distinto basado en uno de estos tipos. La codificación se aplica a los valores de atributo o contenido del elemento.

XMLBINARY USING BASE64: Especifica que la codificación asumida son caracteres " base64 ", tal como se define para el tipo de esquema XML " xs:base64Binary ". La codificación UTF-8 ( base64 ) utiliza un subconjunto de 64 caracteres del US-ASCII (10 dígitos, 26 caracteres en minúscula, 26 caracteres en mayúscula, «+» y «/») para representar cada 6 bits de los datos binarios o de bits mediante un carácter imprimible en el subconjunto. Estos caracteres son una selección concebida especialmente para permitir su representación universal. Además, el carácter «=» representa un carácter de relleno de línea. Con este método, el tamaño de los datos codificados es un 33 % mayor que los datos binarios o de bits originales.
XMLBINARY USING BASE64 es el valor predeterminado.
XMLBINARY USING HEX: Especifica que la codificación asumida son caracteres hexadecimales, tal como se define para la codificación de tipo esquema XML xs:hexBinary. La codificación hexadecimal representa cada byte (8 bits) con dos caracteres hexadecimales. Mediante la utilización de este método, los datos codificados doblan el tamaño de los datos binarios o de bits originales.

Esta función toma un nombre de elemento, una colección opcional de declaraciones de espacio de nombres, una colección opcional de atributos y cero o más argumentos opcionales que componen el contenido del elemento XML. El resultado es una secuencia XML que contiene un nodo de elemento XML o el valor nulo. Si los resultados de todos los argumentos de expresión de contenido de elemento son cadenas vacías, el resultado es una secuencia XML que contiene un elemento vacío.

El resultado de la función es un valor XML. El resultado puede ser nulo; si todos los argumentos de elemento-contenido-expresión son nulos y la opción NULL ON NULL está en vigor, el resultado es el valor nulo.

Notas

Construcción de un nodo de elemento:

El nodo de elemento resultante se construye de la siguiente manera:

xmlnamespace-declaration añade un conjunto de espacios de nombres dentro del ámbito para el elemento construido. Cada espacio de nombres con ámbito asocia un prefijo de espacio de nombres (o el espacio de nombres por omisión) a un URI de espacio de nombres. Los espacios de nombres con ámbito definen el conjunto de prefijos de espacio de nombres que están disponibles para interpretar los QName que se encuentran dentro del ámbito del elemento.
Si se especifica la función xmlattributes, se evalúa y el resultado es una secuencia de nodos de atributo.
Cada expresión-contenido-elemento se evalúa y el resultado se convierte en una secuencia de nodos, tal como se indica a continuación:
- Si el tipo de resultado no es XML, se convierte en un nodo de texto XML que contiene el resultado de la expresión de contenido de elemento que se asigna a XML.
- Si el tipo de resultado es XML, el resultado es una secuencia de elementos. Puede que algunos de los elementos de esa secuencia sean nodos de documentos. Cada nodo de documento de la secuencia se sustituye por la secuencia de sus hijos de nivel superior. A continuación, para cada nodo de la secuencia resultante, se construye una nueva copia en profundidad del nodo, incluidos sus hijos y atributos. Cada nodo copiado tiene una nueva identidad de nodo. A los nodos de elementos copiados se les da la anotación de tipo xdt:untyped, y a los nodos de atributos copiados se les da la anotación de tipo xdt:untypedAtomic. Para cada secuencia adyacente de uno o más valores atómicos que se devuelven en la secuencia, se construye un nuevo nodo de texto que contiene el resultado de convertir cada valor atómico en una cadena, con un único carácter en blanco insertado entre valores adyacentes. Si alguno de estos valores atómicos no puede convertirse en una cadena, se devuelve un error.
La secuencia de resultados de xmlattributes-function y las secuencias resultantes de todas las cláusulas element-content-expression se concatenan en una secuencia que se denomina secuencia de contenido. Cualquier secuencia de nodos de texto adyacentes en la secuencia de contenido se fusiona en un único nodo de texto concatenando sus contenidos, sin espacios intermedios. Después de la concatenación, cualquier nodo de texto que sea una cadena de longitud cero se elimina de la secuencia de contenido.
Si la secuencia de contenido contiene un nodo de atributo que sigue a un nodo que no es un nodo de atributo, se devuelve un error. Los nodos de atributo que aparecen en la secuencia de contenido se convierten en atributos del nuevo nodo de elemento. Si dos o más de estos nodos de atributos tienen el mismo nombre, se devuelve un error. Se crea una declaración de espacio de nombres que se corresponde con cualquier espacio de nombres que se utilice en los nombres de los nodos de atributo si el URI del espacio de nombres no está en los espacios de nombres del ámbito del elemento construido.
Los nodos de elementos, texto, comentarios e instrucciones de proceso de la secuencia de contenido se convierten en los hijos del nodo de elemento construido.
Al nodo del elemento construido se le asigna una anotación de tipo xdt:untyped, y a cada uno de sus atributos se le asigna una anotación de tipo xdt:untypedAtomic. El nombre de nodo del nodo de elemento construido es el nombre de elemento XML que se especifica después de la palabra clave NAME.

Reglas para usar espacios de nombres dentro de XMLELEMENT:

Las siguientes reglas describen el alcance de los espacios de nombres:

Los espacios de nombres que se declaran en la función XMLNAMESPACES son los espacios de nombres del ámbito del nodo de elemento que se construyen mediante la función XMLELEMENT. Si el nodo del elemento se serializa, cada uno de sus espacios de nombres dentro del ámbito se serializará como un atributo de espacio de nombres, a menos que sea un espacio de nombres dentro del ámbito del padre del nodo del elemento y el elemento padre también se serialice.
El alcance de estos espacios de nombres es el alcance léxico de la función XMLELEMENT, incluyendo el nombre del elemento, los nombres de atributos que se especifican en la función XMLATTRIBUTES y todas las expresiones de contenido de elementos. Se utilizan para resolver los QNames en el ámbito.
Si una función XMLQUERY o XMLEXISTS está en una expresión de contenido de elemento, los espacios de nombres se convierten en los espacios de nombres conocidos estáticamente de la expresión de contenido de elemento ( XQuery ) de la función XMLQUERY o XMLEXISTS. Los espacios de nombres conocidos estáticamente se utilizan para resolver los QNames que están en la expresión XQuery . Si el prólogo XQuery declara un espacio de nombres que tiene el mismo prefijo dentro del ámbito de la expresión XQuery , el espacio de nombres que se declara en el prólogo anulará los espacios de nombres que se declaran en la función XMLNAMESPACES.
Si un atributo del elemento construido proviene de la expresión de contenido del elemento, es posible que su espacio de nombres no esté declarado como un espacio de nombres dentro del ámbito del elemento construido. En este caso, se crea un nuevo espacio de nombres para él. Si el prefijo del nombre del atributo ya está vinculado a un URI diferente por un espacio de nombres dentro del ámbito, Db2 genera un prefijo diferente para utilizarlo en el nombre del atributo. Se crea un espacio de nombres para este prefijo generado. El nombre del prefijo generado sigue el siguiente patrón: db2ns-xx, donde xx es un par de caracteres elegidos del conjunto [ A-Z,a-z,0-9 ].

ejemplos

Ejemplo 1:

La siguiente declaración utiliza la función XMLELEMENT para crear un elemento XML que contiene el nombre de un empleado. La declaración también almacena el número de empleado como un atributo llamado serial. Si hay un valor nulo en la columna a la que se hace referencia, la función devuelve el valor nulo:

   SELECT e.empno, e.firstnme, e.lastname,
          XMLELEMENT ( NAME "foo:Emp",
            XMLNAMESPACES('http://www.foo.com' AS "foo"),
            XMLATTRIBUTES(e.empno as "serial"),
                          e.firstnme,
                          e.lastname
                          OPTION NULL ON NULL ) AS "Result"
       FROM EMP e
       WHERE e.edlevel = 12;

El resultado de la consulta sería similar al siguiente resultado:

 EMPNO  FIRSTNME  LASTNAME  Result
-----  --------  --------  ------------------------------------

A0001  John      Parker    <foo:Emp xmlns:foo="http://www.foo.com" 
                                serial="A0001">JohnParker</foo:Emp>
B0001  (null)    Smith     <foo:Emp xmlns:foo="http://www.foo.com" 
                                serial="B0001">Smith</foo:Emp>
B0002  (null)    (null)    (null)
(null) (null)    (null)    (null)

Ejemplo 2:

El siguiente ejemplo es similar al Ejemplo 1, sin embargo, cuando hay un valor nulo en una de las columnas referenciadas, se devuelve un elemento vacío:

   SELECT e.empno, e.firstnme, e.lastname,
     XMLELEMENT (NAME "foo:Emp",
                 XMLNAMESPACES('http://www.foo.com' AS "foo"),
                 XMLATTRIBUTES(e.empno as "serial"),
                               e.firstnme,
                               e.lastname
                            OPTION EMPTY ON NULL) AS "Result"
    FROM EMP e
    WHERE e.edlevel = 12;

El resultado de la consulta sería similar al siguiente resultado:

 EMPNO    FIRSTNME    LASTNAME    Result
 -----    --------    --------    -------------------------------------

 A0001    John        Parker      <foo:Emp xmlns:foo="http://www.foo.com"
                                   serial="A0001">JohnParker</foo:Emp>
 B0001    (null)      Smith       <foo:Emp xmlns:foo="http://www.foo.com"
                                   serial="B0001">Smith</foo:Emp>
 B0002    (null)      (null)      <foo:Emp xmlns:foo="http://www.foo.com"
                                   serial="B0002"/>
 (null)   (null)      (null)      <foo:Emp xmlns:foo="http://www.foo.com"/>