DB2 10.5 for Linux, UNIX, and Windows

XMLSERIALIZE scalar function

The XMLSERIALIZE function returns a serialized XML value of the specified data type generated from the XML-expression argument.


                    .-CONTENT-.   
>>-XMLSERIALIZE--(--+---------+--------------------------------->

>--XML-expression--AS--| data-type |---------------------------->

   .--------------------------------------.      
   V .-VERSION--'1.0'---------------. (1) |      
>----+------------------------------+-----+--)-----------------><
     | .-EXCLUDING XMLDECLARATION-. |            
     '-+-INCLUDING XMLDECLARATION-+-'            

data-type

                    .-(1)----------------------------.                              
|--+-+-CHARACTER-+--+--------------------------------+--------------------------+--|
   | '-CHAR------'  '-(--integer--+-------------+--)-'                          |   
   |                              +-OCTETS------+                               |   
   |                              '-CODEUNITS32-'                               |   
   +-+-VARCHAR----------------+--(--integer--+-------------+--)-----------------+   
   | '-+-CHARACTER-+--VARYING-'              +-OCTETS------+                    |   
   |   '-CHAR------'                         '-CODEUNITS32-'                    |   
   |                                  .-(1M)----------------------------------. |   
   +-+-CLOB------------------------+--+---------------------------------------+-+   
   | '-+-CHARACTER-+--LARGE OBJECT-'  '-(--integer--+---+--+-------------+--)-' |   
   |   '-CHAR------'                                +-K-+  +-OCTETS------+      |   
   |                                                +-M-+  '-CODEUNITS32-'      |   
   |                                                '-G-'                       |   
   |                           .-(1M)-----------------.                         |   
   '-+-BLOB-----------------+--+----------------------+-------------------------'   
     '-BINARY--LARGE OBJECT-'  '-(--integer--+---+--)-'                             
                                             +-K-+                                  
                                             +-M-+                                  
                                             '-G-'

Notes:

The same clause must not be specified more than once.

The schema is SYSIBM. The function name cannot be specified as a qualified name.

CONTENT

Specifies that any XML value can be specified and the result of the serialization is based on this input value.

XML-expression

Specifies an expression that returns a value of data type XML. The XML sequence value must not contain an item that is an attribute node (SQLSTATE 2200W). This is the input to the serialization process.

AS data-type

Specifies the result type. The implicit or explicit length attribute of the specified result data type must be sufficient to contain the serialized output (SQLSTATE 22001).

VERSION '1.0'

Specifies the XML version of the serialized value. The only version supported is '1.0' which must be specified as a string constant (SQLSTATE 42815).

EXCLUDING XMLDECLARATION or INCLUDING XMLDECLARATION

Specifies whether an XML declaration is included in the result. The default is EXCLUDING XMLDECLARATION.

EXCLUDING XMLDECLARATION

Specifies that an XML declaration is not included in the result.

INCLUDING XMLDECLARATION

Specifies that an XML declaration is included in the result. The XML declaration is the string '<?xml version="1.0" encoding="UTF-8"?>'.

AS data-type

Specifies the result data type. The implicit or explicit length attribute of the specified result data type must be sufficient to contain the transformed output (SQLSTATE 22001).

If either the xml-document argument or the xsl-stylesheet argument is null, the result will be null.

Code page conversion might occur when storing any of the previously mentioned documents in a CHAR, VARCHAR, or CLOB column, which might result in a character loss.

The result has the data type specified by the user. An XML sequence is effectively converted to have a single document node by applying XMLDOCUMENT to XML-expression before serializing the resulting XML nodes. If the result of XML-expression can be null, the result can be null; if the result of XML-expression is null, the result is the null value.

Notes

Encoding in the serialized result: The serialized result is encoded with UTF-8. If XMLSERIALIZE is used with a character data type, and the INCLUDING XMLDECLARATION clause is specified, the resulting character string containing serialized XML might have an XML encoding declaration that does not match the code page of the character string. Following serialization, which uses UTF-8 encoding, the character string that is returned from the server to the client is converted to the code page of the client, and that code page might be different from UTF-8.
Therefore, applications should avoid direct use of XMLSERIALIZE INCLUDING XMLDECLARATION that return character string types and should retrieve XML values directly into host variables to maintain the match between the external code page and the encoding in the XML declaration. If XMLSERIALIZE must be used in this situation, a BLOB type should be specified to avoid code page conversion.
Syntax alternative: XML2CLOB(XML-expression) can be specified in place of XMLSERIALIZE(XML-expression AS CLOB(2G)). It is supported only for compatibility with previous DB2® releases.