XML serialization

XML serialization is the process of converting XML data from its internal representation in a DB2® table to the textual XML format that it has in an application.

You can invoke the XMLSERIALIZE function, to request that the DB2 database server perform XML serialization before it sends the XML data to the client application. This process is called explicit serialization. Alternatively, you can omit the XMLSERIALIZE call, and retrieve data from an XML column directly into application variables. The DB2 database server serializes the XML data during retrieval. This process is called implicit serialization.

With implicit serialization, the data has the XML type when it is sent to the client, if the client supports the XML data type. For DB2 ODBC and embedded SQL applications, the DB2 database server adds an XML declaration, with the appropriate encoding specification, to the data. For Java applications, the DB2 database server does not add an XML declaration, unless you use the deprecated DB2Xml.getDB2Xmlxxx methods to retrieve the data.

Implicit serialization is the preferred method in most cases. Sending XML data to the client allows the DB2 client to handle the XML data properly. Explicit serialization requires additional handling by the client.

Start of change You can retrieve XML data in the binary XML format (Extensible Dynamic Binary XML DB2 Client/Server Binary XML Format), rather than as textual XML data, to avoid serialization. Retrieval of data in the binary XML format is supported only in JDBC, SQLJ, or ODBC applications, or by the UNLOAD utility. End of change

After an explicit XMLSERIALIZE invocation, the data has a non-XML data type in the database server, and is sent to the client as that data type.

XMLSERIALIZE lets you specify:

The SQL data type to which the data is converted when it is serialized
The data type is a CLOB, BLOB, DBCLOB data type.
Whether the output data should include the following explicit XML declaration (EXCLUDING XMLDECLARATION or INCLUDING XMLDECLARATION):
```
<?xml version="1.0" encoding="UTF-8"?>
```

The output from XMLSERIALIZE is Unicode UTF-8-encoded data.

Be sure that you understand the implications of requesting an explicit encoding specification when you execute XMLSERIALIZE. If you retrieve the textual XML data into a non-binary data type, the data is converted to the application encoding, but the encoding specification is not modified. Therefore, the encoding of the data might not agree with the encoding specification. This situation results in XML data that cannot be parsed by application processes that rely on the encoding name.

In general, implicit serialization is preferable. However, under the following circumstances, it is better to do an explicit XMLSERIALIZE:

When XML documents are very large
Because there are no XML locators, if the XML documents are very large, you can use XMLSERIALIZE to convert the data to a LOB type so that you can use LOB locators.
When the client does not support XML data
If the client is an earlier version that does not support the XML data type, and you use implicit XML serialization, the DB2 database server converts the data to the BLOB data type. If you want the retrieved data to be some other data type, you can dynamically execute an SQL statement that invokes XMLSERIALIZE to specify CLOB or DBCLOB output.
When you want to pass XML data to a stored procedure or user-defined function
DB2 for z/OS® stored procedures and user-defined functions do not support parameters with the XML data type. Therefore, if you want to pass data from an XML column to a routine, you need to invoke XMLSERIALIZE on the data to convert it to a BLOB, CLOB, or DBCLOB type.

The best data type to which to convert XML data is the BLOB data type, because retrieval of binary data results in fewer encoding issues.

Example: XML column Info in sample table Customer contains a document that contains the hierarchical equivalent of the following data:

<customerinfo xml:space="default" xmlns="http://posample.org" Cid='1000'>
  <name>Kathy Smith</name>
  <addr country='Canada'>
  <street>5 Rosewood</street>
  <city>Toronto</city>
  <prov-state>Ontario</prov-state>
  <pcode-zip>M6W 1E6</pcode-zip>
  </addr>
  <phone type='work'>416-555-1358</phone>
</customerinfo>

Invoke XMLSERIALIZE to serialize the data and convert it to a BLOB type before retrieving it into a host variable.

SELECT XMLSERIALIZE(Info as BLOB(1M)) from Customer
  WHERE CID='1000'

Example: In a C program, retrieve the customerinfo document for customer ID 1000 into an XML as BLOB host variable. Doing this results in implicit XML serialization. The retrieved data is in the UTF-8 encoding scheme, and it contains an XML declaration.

EXEC SQL BEGIN DECLARE SECTION;
 SQL TYPE IS XML AS BLOB (1M) xmlCustInfo;
EXEC SQL END DECLARE SECTION;
…
EXEC SQL SELECT INFO INTO :xmlCustInfo
  FROM Customer
  WHERE Cid=1000;

Example: This JDBC program avoids XML serialization by retrieving the data in the binary data format. The program sets the DataSource property xmlFormat to indicate that the data should be retrieved in the binary XML format. Then the program retrieves the customerinfo document for customer ID 1000 into an SQLXML object. Next, the program retrieves the data from the SQLXML object into a DOMSource object, so that the retrieved data is in a non-textual representation. This technique requires JDBC 4.0 or later.

import java.sql.*;                        // JDBC base
import com.ibm.db2.jcc.*;                 // IBM Data Server Driver for JDBC
                                          // and SQLJ implementation of JDBC
…
com.ibm.db2.jcc.DB2SimpleDataSource db2ds =  
  new com.ibm.db2.jcc.DB2SimpleDataSource();
                                          // Create the DataSource object
db2ds.setDriverType(4);                   // Set the driver type
db2ds.setDatabaseName("san_jose");        // Set the location
db2ds.setUser("db2adm");                  // Set the user
db2ds.setPassword("db2adm");              // Set the password
db2ds.setServerName("mvs1.sj.ibm.com");  
                                          // Set the server name
db2ds.setPortNumber(5021);                // Set the port number
db2ds.setXMLFormat(
  com.ibm.db2.jcc.DB2BaseDataSource.XML_FORMAT_BINARY);
                                          // Set XML format to binary
…
Statement stmt = conn.createStatement();
ResultSet rs = stmt.executeQuery("SELECT INFO FROM Customer WHERE Cid='1000'");
SQLXML sqlxml = rs.getSQLXML(1);
DOMSource domSource = sqlxml.getSource(DOMSource.class); 
                                         // Get a DOMSource object from 
                                         // the SQLXML object, to avoid
                                         // XML serialization
Document document = (Document) domSource.getNode();