XML Storage in IMS Databases

To store XML in an IMS database or to retrieve XML from IMS, you must first generate an XML schema and the IMS Java metadata class using the DLIModel utility. The metadata and schema are used during the storage and retrieval of XML. Your application uses the IMS Java JDBC user-defined functions (UDFs) storeXML and retrieveXML to store XML in IMS databases, create XML from IMS data, or retrieve XML documents from IMS databases.

Figure 18-8 on page 322 shows the overall process for storing and retrieving XML in IMS.

Figure 18-8. Overview of XML Storage in IMS

retrieveXML UDF

The retrieveXML UDF creates an XML document from an IMS database and returns an object that implements the java.sql.Clob interface. It does not matter to the application whether the data is decomposed into standard IMS segments or the data is in intact XML documents in the IMS database.

The Clob JDBC type stores a character large object as a column value in a row of the result set. The getClob method retrieves the XML document from the result set. Figure 18-9 shows the relationship between the retrieveXML UDF and the getClob method.

Figure 18-9. Creating XML Using the `retrieveXML` UDF and the `getClob` Method

To create an XML document, use a retrieveXML UDF in the SELECT statement of your JDBC call. Pass in the name of the segment that will be the root element of the XML document (for example, retrieveXML(Model)). The dependent segments of the segment that you pass in will be in the generated XML document if they match the criteria listed in the WHERE clause.

The segment that you specify to be the root element of the XML document does not have to be the root segment of the IMS record. The dependent segments are mapped to the XML document based on the generated XML schema.

storeXML UDF

The storeXML UDF inserts an XML document into an IMS database at the position in the database that the WHERE clause indicates. IMS, not the application, uses the XML schema and the Java metadata class to determine the physical storage of the data into the database. It does not matter to the application whether the XML is stored intact or decomposed into standard IMS segments.

An XML document must be valid before it can be stored into a database. The storeXML UDF validates the XML document against the XML schema before storing it. If you know that the XML document is valid and you do not want IMS to revalidate it, use the storeXML(false) UDF.

To store an XML document, use the storeXML UDF in the INSERT INTO clause of a JDBC prepared statement. Within a single application program, you can issue INSERT calls that contain storeXML UDFs against multiple PCBs in an application's PSB.

The SQL query must have the following syntax:

 INSERT INTO PCB.Segment (storeXML()) VALUES ( ? ) WHERE Segment.Field = value

Decomposed Storage Mode for XML

In decomposed storage mode, all elements and attributes are stored as regular fields in optionally repeating DL/I segments. During parsing, all tags and other XML syntactic information are checked for validity and then discarded. The parsed data is physically stored in the database as standard IMS data, meaning that each defined field in the segment is of an IMS standard type. Because all XML data is composed of string types (typically Unicode) with type information existing in the validating XML schema, each parsed data element and attribute can be converted to the corresponding IMS standard field value and stored into the target database.

Inversely, during XML retrieval, DL/I segments are retrieved, fields are converted to the destination XML encoding, tags and XML syntactic information (stored in the XML schema) are added, and the XML document is composed.

Figure 18-10 shows how XML elements are decomposed and stored into IMS segments.

Figure 18-10. How XML Is Decomposed and Stored in IMS Segments

Decomposed storage mode is suitable for data-centric XML documents, where the elements and attributes from the document typically are either character or numeric items of known short or medium length that lend themselves to mapping to fields in segments. Lengths are typically, though not always, fixed.

The XML document data can start at any segment in the hierarchy, which is the root element in the XML document. The segments in the subtree below this segment are also included in the XML document. Elements and attributes of the XML document are stored in the dependent segments of the root element segment. Any other segments in the hierarchy that are not dependent segments of that root element segment are not part of the XML document and, therefore, are not described in the describing XML schema.

When an XML document is stored in the database, the value of all segment fields is extracted directly from the XML document. Therefore, any unique key field in any of the XML segments must exist in the XML document as an attribute or simple element.

The XML hierarchy is defined by a PCB hierarchy that is based on either a physical or a logical database. Logical relationships are supported for retrieval and composition of XML documents, but not for inserting documents.

For a legacy database, either the whole database hierarchy or any subtree of the hierarchy can be considered as a decomposed data-centric XML document. The segments and fields that comprise the decomposed XML data are determined only by the definition of a mapping (the XML schema) between those segments and fields and a document.

One XML schema is generated for each database PCB. Therefore, multiple documents may be derived from a physical database hierarchy through different XML schemas. There are no restrictions on how these multiple documents overlap and share common segments or fields.

A new database can be designed specifically to store a particular type of data-centric XML document in decomposed form.

Intact Storage Mode for XML

In intact storage mode, all or part of an XML document is stored intact in a field. The XML tags are not removed and IMS does not parse the document. XML documents can be large, so the documents can span the primary intact field, which contains the XML root element, and fields in overflow segments. The segments that contain the intact XML documents are standard IMS segments and can be processed like any other IMS segments. The fields, because they contain unparsed XML data, cannot be processed like standard IMS fields. However, intact storage of documents has the following advantages over decomposed storage mode:

IMS does not need to compose or decompose the XML during storage and retrieval. Therefore, you can process intact XML documents faster than decomposed XML documents.
You do not need to match the XML document content with IMS field data types or lengths. Therefore, you can store XML documents with different structure, content, and length within the same IMS database.

Intact XML storage requires a new IMS database or an extension of an existing database because the XML document must be stored in segments and fields that are specifically tailored for storing intact XML.

To store all or part of an XML document intact in an IMS database, the database must define a base segment, which contains the root element of the intact XML subtree. The rest of the intact XML subtree is stored in overflow segments, which are child segments of the base segment.

The base segment contains the root element of the intact XML subtree and any decomposed or non-XML fields. The format of the base segment is defined in the DBD.

The overflow segment contains only the overflow XML data field. The format of the overflow XML data field is defined in the DBD.

Side Segments for Secondary Indexing

IMS cannot search intact XML documents for specific elements within the document. However, you can create a side segment that contains specific XML element data. IMS stores the XML document intact, and also decomposes a specific piece of XML data into a standard IMS segment. This segment can then be searched with a secondary index.

Figure 18-11 shows a base segment, an overflow segment, and the side segment for secondary indexing.