SQL/XML DB2

Скалярная функция XMLELEMENT

 
>>-XMLELEMENT--(--NAME--имя-элемента---------------------------->
 
>--+-------------------------------------+---------------------->
   '-,--объявление-пространства имен-xml-'
 
>--+--------------------------+--------------------------------->
   '-,--функция-XMLATTRIBUTES-'
 
>--+---------------------------------------+-------------------->
   | .-----------------------------------. |
   | V                                   | |
   '---,--выражение-содержимого-элемента-+-'
 
>--+------------------------------------------------------------+-->
   |              .-------------------------------------------. |
   |        (1)   V   .-EMPTY ON NULL-. (2)              (3)  | |
   '-OPTION---------+-+-NULL ON NULL--+----------------+------+-'
                    |              .-USING-.           |
                    | .-XMLBINARY--+-------+--BASE64-. |
                    | |            .-USING-.         | |
                    '-+-XMLBINARY--+-------+--HEX----+-'
 
>--)-----------------------------------------------------------><

Примечания:

Фраза OPTION может задаваться только, если задано не менее одной функции-XMLATTRIBUTES или выражения-содержимого-элемента.
NULL ON NULL или EMPTY ON NULL может задаваться только, если задано не менее одного выражения-содержимого-элемента.
Одна и та же фраза не должна задаваться более одного раза.

Схема - SYSIBM. Имя функции не может быть задано как квалифицированное имя.

Функция XMLELEMENT Возвращает XML-значение, которое является элементным узлом XQuery.

NAME имя-элемента

Задает имя элемента XML. Имя является идентификатором SQL, который должен быть в форме квалифицированного имени XML или QName (SQLSTATE 42634). См. подробнее о допустимых именах в спецификациях пространства имен W3C. Если имя квалифицировано, то префикс пространства имен должен быть объявлен в области видимости (SQLSTATE 42635).

объявление-пространства имен-xml

Задает объявления пространств имен XML, которые являются результатом функции XMLNAMESPACES. Пространства имен, которые объявлены, находятся в области видимости функции XMLELEMENT. Пространства имен применяются ко всем вложенным функциям XML внутри функции XMLELEMENT, даже если они появляются внутри другого подзапроса.
Если объявление-пространства имен-xml не задано, объявления пространств имен с конструируемым элементом не связываются.

функция-XMLATTRIBUTES

Задает атрибуты XML для элемента. Атрибуты являются результатом функции XMLATTRIBUTES.

выражение-содержимого-элемента

Содержимое генерируемого элементного узла XML задается выражением или списком выраженией. Тип данных выражения-содержимого-элемента не может быть структурированным. Выражение может быть любым SQL-выражением.
Если выражение-содержимого-элемента не задается, в качестве содержимого элемента используется пустая строка и OPTION NULL ON NULL или EMPTY ON NULL не должны задаваться.

OPTION

Задает дополнительные опции для конструирования элемента XML. Если фраза OPTION не задана, по умолчанию принимается EMPTY ON NULL XMLBINARY USING BASE64. Эта фраза не влияет на вложенные вызовы XMLELEMENT, заданные в выражении-содержимого-элемента.
EMPTY ON NULL или NULL ON NULL
Задает, должно возвращаться значение null или пустой элемент, если - значение каждого выражения-содержимого-элемента - значение null. Эта опция влияет только на значения null в содержимом элемента, а не в значениях атрибутов. По умолчанию принимается EMPTY ON NULL.
EMPTY ON NULL
Если значение каждого выражения-содержимого-элемента - null, возвращается пустой элемент.

NULL ON NULL
Если значение каждого выражения-содержимого-элемента - null, возвращается значение null.

XMLBINARY USING BASE64 или XMLBINARY USING HEX
Задает подразумеваемую кодировку двоичных входных данных, символьных строк с атрибутом FOR BIT DATA или различимых типов, базирующихся на этих типах. Кодировка применяется к содержимому элемента или к значениям атрибутов. По умолчанию принимается XMLBINARY USING BASE64.
XMLBINARY USING BASE64
Задает подразумеваемую кодировку base64, как определено для типа XML-схемы xs:base64Binary. Кодировка base64 использует 65-символьное подмножество US-ASCII (10 цифр, 26 символов нижнего регистра, 26 символов верхнего регистра, '+' и '/') для представления каждых шести бит двоичных или битовых данных. Эти символы выбраны так, что они универсально представимы. При использовании этого метода размер кодированных данных на 33 процента больше, чем исходных двоичных или битовых данных.

XMLBINARY USING HEX
Задает подразумеваемую кодировку в 16-ричных символах, как определено для типа XML-схемы xs:hexBinary. 16-ричнвя кодировка представляет каждый байт (8 бит) двумя 16-ричными цифрами. При использовании этого метода размер кодированных данных вдвое больше, чем исходных двоичных или битовых данных.

Эта функция принимает имя элемента и - необязательно - коллекцию объявлений пространств имен, необязательно - коллекцию атрибутов и ноль или более аргументов, которые составляют содержимое элемента XML. Результатом является XML-последовательность, содержащая узел элемента XML или значение null.

Тип данных результата - XML. Если любой из аргументов выражения-содержимого-элемента может быть null, результат может быть null; если все значения аргументов выражения-содержимого-элемента - null и работает опция NULL ON NULL, результат - значение null.

Примечания:

Поддержка в базах данных не-Unicode и базах данных с многими разделами: Функция поддерживается только как в версии 8. Результат на внешнем уровне вложений функций с XML-значением должен быть аргументом функции XMLSERIALIZE. Опции обработки null и двоичного кодирования задаваться не могут (SQLSTATE 42997). BLOB и данные символьной строки, определенные как FOR BIT DATA задаваться не могут (SQLSTATE 42884).
Конструирование элементного узла: Результирующий элементный узел конструируется следующим образом:
- Объявление-пространства имен-xml добавляет набор пространств имен в области видимости для конструируемого элемента. Каждое пространство имен в области видимости связывает префикс пространства имен (или пространство имен по умолчанию) с URI пространства имен. Пространства имен в области видимости определяют набор префиксов пространств имен, которые доступны для интерпретации QNames в области видимости элемента.
- Если задана функция-XMLATTRIBUTES, она вычисляется и результат является последовательностью узлов атрибутов.
- Каждое выражение-содержимого-элемента вычисляется и результат преобразуется в последовательность узлов следующим образом:
  - Если тип результата - не XML, он преобразуется в текстовый узел XML, содержимое которого является результатом выражения-содержимого-элемента, отображенным на XML в соответствии с правилами отображения значений данных SQL на значения данных XML (см. таблицу, которая описывает поддерживаемые преобразования из значений не-XML в значения XML в "Преобразования типов данных").
  - Если тип результата - XML, то в общем случае результат является последовательностью пунктов. Некоторые из пунктов в этой последовательности могут быть документными узлами. Каждый узел документа в последовательности заменяется на последовательность его потомков первого уровня. Затем для каждого узла в результирующей последовательности конструируется новая глубокая копия, включающая его потомков и атрибуты. Каждый скопированный узел имеет новую идентификацию узла. Скопированные узлы элементов и атрибутов сохраняют свои аннотации типов. Для каждой последовательность из одного или более смежных атомарных значений, возвращенной в последовательности, конструируется новый текстовый узел, содержащий результат преобразования каждого атомарного значения в строку с одним пробелом, вставляемым между соседними значениями. Смежные текстовые узлы в контентной последовательности сливаются в один текстовый узел конкатенацией их содержимого, без пробелов. После конкатенации все текстовые узлы, содержимое которых - строка нулевой длины, удаляются из контентной последовательности.
- Результирующая последовательность атрибутов XML и результирующие последовательности всех выражений-содержимого-элемента сцепляются в одну последовательность, которая называется контентной последовательностью. Любая последовательность смежных текстовых узлов в контентной последовательность сливается в один текстовый узел. Если все аргументы выражения-содержимого-элемента являются пустыми строками или аргумент выражения-содержимого-элемента не задан, возвращается пустой элемент.
- Контентная последовательность не должна содержать узел атрибут, следующий за узлом, который не является узлом атрибута (SQLSTATE 10507). Узлы атрибутов, встречающиеся в контентной последовательности становятся атрибутами нового узла элемента. Два или более таких узлов атрибутов не должны иметь одинакового имени (SQLSTATE 10503). Объявление пространства имен создается для любого пространства имен, используемого в именах узлов атрибутов, если URI пространства имен не находится в пространствах имен области видимости конструируемого элемента.
- Узлы элементов, текста, комментариев и инструкций обработки в контентной последовательности становятся потомками конструируемого элементного узла.
- Конструируемый элементный узел получает аннотацию типа xs:anyType, и каждый из его атрибутов получает аннотацию типа xdt:untypedAtomic. Имя узла конструируемого элементного узла является именем-элемента, заданным после ключевого слова NAME.
Правила для использования пространств имен внутри XMLELEMENT: Следующие правила относятся к области видимости пространств имен:
- Пространства имен, объявленные в объявлении XMLNAMESPACES являются пространствами имен в области видимости элементного узла, конструируемого функцией XMLELEMENT. Если элементный узел сериализуется, то каждое из его пространств имен в области видимости будет сериализовано как атрибут пространства имен, кроме случая, когда оно является пространством имен в области видимости предка элементного узла и элемент-предок также сериализуется.
- Если в выражении-содержимого-элемента есть XMLQUERY или XMLEXISTS, то пространства имен становятся статически известными пространствами имен выражения XQuery в XMLQUERY или XMLEXISTS. Статически известные пространства имен используются для разрешения QNames в выражении XQuery. Если пролог XQuery объявляет пространство имен с тем же префиксом в области видимости выражения XQuery, пространство имен, объявленное в прологе, замещает пространство имен, объявленное в объявлении XMLNAMESPACES.
- Если атрибут конструируемого элемента поступает из выражения-содержимого-элемента, его пространство имен может не быть объявленным как пространство имен в области видимости конструируемого элемента, в этом случае для него создается новое пространство имен. Если это приводит к конфликту, что означает, что префикс имени атрибута уже привязан к другому URI пространством имен в области видимости, DB2 генерирует префикс, который не приводит к такому конфликту, и префикс, используемый в имени атрибут, заменяется на новый префикс, и для этого нового префикса создается пространство имен. Генерируемый новый префикс соответствует следующему шаблону: "db2ns-xx", где "x" - символ, выбираемый из набора [A-Z,a-z,0-9]. Например:
```
 
VALUES XMLELEMENT(
     NAME "c", XMLQUERY(
       'declare namespace ipo="www.ipo.com"; $m/ipo:a/@ipo:b' PASSING XMLPARSE(
         DOCUMENT '<tst:a xmlns:tst="www.ipo.com" tst:b="2"/>'
       ) AS "m"
     )
)
```
  возвращает:
```
 
<c xmlns:tst="www.ipo.com" tst:b="2"/>
```
  Второй пример:
```
 
VALUES XMLELEMENT(
     NAME "tst:c", XMLNAMESPACES(
       'www.tst.com' AS "tst"
     ),
     XMLQUERY(
       'declare namespace ipo="www.ipo.com"; $m/ipo:a/@ipo:b' PASSING XMLPARSE (
         DOCUMENT '<tst:a xmlns:tst="www.ipo.com" tst:b="2"/>'
       ) AS "m"
     )
   )
```
  возвращает:
```
 
<tst:c xmlns:tst="www.tst.com" xmlns:db2ns-a1="www.ipo.com" db2ns-a1:b="2"/>
```

Примеры:

Сконструировать элемент с опцией NULL ON NULL.

 
SELECT E.FIRSTNME, E.LASTNAME, XMLELEMENT(
     NAME "Emp", XMLELEMENT(
       NAME "firstname", E.FIRSTNME
     ), 
     XMLELEMENT(
       NAME "lastname", E.LASTNAME
     )
     OPTION NULL ON NULL
   )
   AS "Result"
   FROM EMPLOYEE E
   WHERE E.EDLEVEL = 12

Этот запрос вырабатывает следующий результат (форматирован для читабельности):

 
FIRSTNME     LASTNAME        Emp
JOHN         PARKER          <Emp><firstname>JOHN</firstname>
                               <lastname>PARKER</lastname></Emp>
MAUDE        SETRIGHT        <Emp><firstname>MAUDE</firstname>
                               <lastname>SETRIGHT</lastname></Emp>
MICHELLE     SPRINGER        <Emp><firstname>MICHELLE</firstname>
                               <lastname>SPRINGER</lastname></Emp>

Сделать элемент со списком элементов, вложенных как дочерние элементы.

 
SELECT XMLELEMENT(
     NAME "Department", XMLATTRIBUTES(
       E.WORKDEPT AS "name"
     ),
     XMLAGG (
       XMLELEMENT (
         NAME "emp", E.FIRSTNME
       )
       ORDER BY E.FIRSTNME
     )
   )
   AS "dept_list"
   FROM EMPLOYEE E
   WHERE E.WORKDEPT IN ('A00', 'B01')
   GROUP BY WORKDEPT

Этот запрос вырабатывает следующий результат:

 
dept_list
<Department name="A00">
<emp>CHRISTINE</emp>
<emp>SEAN</emp>
<emp>VINCENZO</emp>
</Department>
<Department name="B01">
<emp>MICHAEL</emp>
</Department>