DB2 10.5 for Linux, UNIX, and Windows

Versioning of XML documents

To support extensibility in future releases, the common SQL API stored procedures return XML output documents that include version information.

Whenever the structure of an XML output document changes (for example, when an element is added or removed), the version levels are incremented. Therefore, a procedure might support several versions of the XML output document.

Version information in the XML document is expressed as key-value pairs for document type major version and document type minor version. For example, an XML output document might define the following keys and values in a dictionary element:

   <key>Document Type Name</key><string>Data Server Configuration Output</string>
   <key>Document Type Major Version</key><integer>2</integer>
   <key>Document Type Minor Version</key><integer>0</integer>

When you call the procedure, you specify the major version and minor version of the XML document that you want to return. The contents of the XML output document will vary depending on the values that you specify.

For example, the GET_CONFIG procedure retrieves the database and database manager configuration parameters that are set for a particular instance. When this procedure is called with major_version 2 and minor_version 0, it returns an XML document that contains configuration parameters grouped into categories. However, when the same procedure is called with major_version 1 and minor_version 0, it returns an XML document that contains configuration parameters, but they are not grouped into categories.

Likewise, the GET_MESSAGE procedure retrieves the message text and SQLSTATE for a specified SQLCODE. When this procedure is called with major_version 2 and minor_version 0, it returns an XML document that contains the short text message, long text message, and SQLSTATE for the corresponding SQLCODE. However, when the same procedure is called with major_version 1 and minor_version 0, it returns an XML document that contains only the short text message and SQLSTATE. The long text message is not available in version 1 of the document.

To determine the highest supported document versions for a procedure, specify NULL for major_version, minor_version, and all other input parameters. The procedure returns the highest supported document versions as values in the major_version and minor_version output parameters, and sets the xml_output and xml_message output parameters to NULL.

If you specify non-null values for major_version and minor_version, you must specify supported document versions, or the procedure raises an error (-20457) to indicate that the procedure encountered an unsupported version.

XML input documents can optionally include values for the document type major version and document type minor version. If these values are specified in the XML input document, then the values passed for major_version and minor_version in the procedure call must exactly match the values that are specified in the XML document, or the procedure raises an error (+20458). This behavior ensures that the caller does not specify an unsupported version of the XML input document.