XMLSERIALIZE scalar function
The XMLSERIALIZE function returns a serialized XML value of the specified data type generated from the XML-expression argument.
The schema is SYSIBM. The function name cannot be specified as a qualified name.
- Specifies that any XML value can be specified and the result of the serialization is based on this input value.
- 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.
- 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
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.