Importing and Exporting XML Data

P3/COBOL includes powerful and flexible extensions to enable importing and exporting COBOL data to/from virtually any form. Based on a pipeline of XML content handlers, this provides the most straight-forward and efficient interface possible between COBOL and the XML document world. This means that COBOL programs can fully participate in any system that uses XML for data interchange or storage or any system that utilizes a format that can be represented as XML. The philosophy of P3/COBOL differs from that of most other implementations of COBOL XML support in that it is based on the congruence of the XML data model and the COBOL data model. Differences between the models (e.g., XML attributes have no equivalent in COBOL’s historic model) are reconciled and eliminated through the use of XML Style-sheet Language for Transformation (XSLT) transforms, rather than through complex proprietary extensions to the COBOL model to achieve precise equivalence.

The P3/COBOL approach assumes that XML data is not just persisted in files, but rather can be produced, stored and retrieved from many locations, even in transient form.

Internally, P3/COBOL uses the very efficient SAX-based parsing/generation of XML that does not require any intermediate Document Object Model storage of the data. This ensures that even the largest external XML documents can be processed.

With the provision of only two extension statements, any possible XML/COBOL interchange need can be met.

IMPORT

In order to consume XML data, P3/COBOL provides the IMPORT statement. This statement allows you to specify the group-level item (identifier) into which you wish to import elements and values from an XML document. The source of the XML may be specified as a file, a Universal Resource Identifier (URI) specifying a web location, a data item or literal within the program, or a mnemonic name that has been assigned to a non-file source in the SPECIAL NAMES paragraph of the program’s CONFIGURATION SECTION. Between the source of the XML document and the destination data item, you may optionally specify a filter pipeline comprising one or more XSLT style sheet transforms accessed via a file or non-file source specified in the same manner as the XML document source.

The operation of the IMPORT statement begins by reading the specified XML source and applying the first filter XSLT style sheet (if any). The next specified filter then processes the output of that transformation in the same manner until all of the specified filters have been used. The final output of the last filter is then processed to assign values to items within and including the specified destination identifier as follows.

XML data elements are assigned to COBOL items as if a MOVE statement were executed that specified the content of the XML element as the source and the correspondingly named element within the destination group as the target. The XML element’s ancestors serve as COBOL qualifiers to resolve any ambiguity in determining the target item. This means that just as qualifiers need not be present for every ancestor group in COBOL, the incoming XML may omit some or all of the ancestor elements if not required for qualification. This powerful feature allows convenient mapping of XML elements to COBOL items that can be used to great advantage. Also, the IMPORT statement assumes that each occurrence of an XML element represents consecutive occurrences of the corresponding destination element, if any. In other words, items in the identifier structure that contain the OCCURS clause are not ignored, but are given consecutive subscript values corresponding to the occurrence number of any repeated congruent source element. Any XML elements for which no congruent destination element exists may ignored by the IMPORT. If the number of occurrences of a repeating COBOL element are insufficient to store all of the corresponding repeating elements in the XML document, any ON EXCEPTION statements are executed, if present. If present, subscript attributes on the incoming XML elements force the IMPORT statement to place the element data in a specific occurrence of the COBOL data item.

The syntax that may be used for the IMPORT statement is:

$\mathsf{IMPORT} \mathit{identifier} \begin{bmatrix} \mathsf{FROM} \end{bmatrix} \mathsf{XML} \begin{Bmatrix*}[l] \mathsf{FILE} \space \mathit{fileName}\\ \mathsf{URI} \space \mathit{system} \text{\textunderscore} \mathit{id}\\ \mathit{identifier}\\ \mathit{literal}\\ \end{Bmatrix*}\\ \quad \begin{bmatrix} \begin{Bmatrix} \mathsf{THRU}\\ \mathsf{THROUGH} \end{Bmatrix} \begin{Bmatrix*}[l] \mathsf{FILE} \space \mathit{fileName}\\ \mathsf{URI} \space \mathit{system} \text{\textunderscore} \mathit{id}\\ \mathit{identifier}\\ \mathit{literal}\\ \end{Bmatrix*} \cdots\\ \end{bmatrix}\\ \quad \begin{bmatrix} \begin{bmatrix} \mathsf{ON} \end{bmatrix} \mathsf{EXCEPTION} \begin{Bmatrix} \mathit{statement} \begin{bmatrix} \begin{bmatrix} \mathsf{THEN} \end{bmatrix} \mathit{statement} \end{bmatrix} \cdots\\ \begin{Bmatrix} \mathit{statement} \begin{bmatrix} \begin{bmatrix} \mathsf{THEN} \end{bmatrix} \mathit{statement} \end{bmatrix} \cdots\\ \end{Bmatrix} \end{Bmatrix}\\ \end{bmatrix}\\ \quad \begin{bmatrix} \mathsf{NOT} \begin{bmatrix} \mathsf{ON} \end{bmatrix} \mathsf{EXCEPTION} \begin{Bmatrix} \mathit{statement} \begin{bmatrix} \begin{bmatrix} \mathsf{THEN} \end{bmatrix} \mathit{statement} \end{bmatrix} \cdots\\ \begin{Bmatrix} \mathit{statement} \begin{bmatrix} \begin{bmatrix} \mathsf{THEN} \end{bmatrix} \mathit{statement} \end{bmatrix} \cdots\\ \end{Bmatrix} \end{Bmatrix}\\ \end{bmatrix}\\ \mathsf{END} \text{-} \mathsf{IMPORT}$

EXPORT

In order to generate XML data, P3/COBOL provides the EXPORT statement. This statement allows you to specify the group-level item (identifier) from which you wish to export the data contents into elements and values in an XML document form. The destination of the XML may be specified as a file, a Universal Resource Identifier (URI) specifying a web location, a data item or literal within the program, or a mnemonic name that has been assigned to a non-file destination in the SPECIAL NAMES paragraph of the program’s CONFIGURATION SECTION. Between the source identifier’s data and the destination XML document you may optionally specify a filter pipeline comprising one or more XSLT style sheet transforms accessed via a file or non-file source specified in the same manner as the XML document destination.

The EXPORT statement may also be used to export an P3/COBOL data schema (as XML) rather than the actual content of the data elements. This schema may then be processed by one or more XSLT transforms, if desired, in order to produce the schema information is virtually any standard or proprietary file format.

The operation of the EXPORT statement begins by encoding the specified identifier and its subordinate groups and elements as an XML source with XML elements corresponding to each non-filler data item. The elementary items’ content is encoded as XML values whose XML Schema type corresponds to the COBOL usage. The first filter XSLT style sheet (if any) is then applied to the resulting document. The next specified filter then processes the output of that transformation in the same manner until all of the specified filters have been used. The final output of the last filter is then written to the specified destination.

If the WITH FILLER phrase is present, FILLER items are included in the exported document by assigning the XML element name “filler” to the item.

The syntax that may be used for the EXPORT statement is:

$\mathsf{EXPORT} \mathit{identifier} \begin{bmatrix} \mathsf{TO} \end{bmatrix} \mathsf{XML} \begin{Bmatrix*}[l] \mathsf{FILE} \space \mathit{fileName}\\ \mathsf{URI} \space \mathit{system} \text{\textunderscore} \mathit{id}\\ \mathit{identifier}\\ \mathit{mnemonic} \text{\textunderscore} \mathit{name}\\ \end{Bmatrix*}\\ \quad \begin{bmatrix} \begin{Bmatrix} \mathsf{THRU}\\ \mathsf{THROUGH} \end{Bmatrix} \begin{Bmatrix*}[l] \mathsf{FILE} \space \mathit{fileName}\\ \mathsf{URI} \space \mathit{system} \text{\textunderscore} \mathit{id}\\ \mathit{identifier}\\ \mathit{literal}\\ \mathit{mnemonic} \text{\textunderscore} \mathit{name}\\ \end{Bmatrix*} \cdots\\ \end{bmatrix}\\ \quad \begin{bmatrix} \begin{bmatrix} \mathsf{ON} \end{bmatrix} \mathsf{EXCEPTION} \begin{Bmatrix} \mathit{statement} \begin{bmatrix} \begin{bmatrix} \mathsf{THEN} \end{bmatrix} \mathit{statement} \end{bmatrix} \cdots\\ \begin{Bmatrix} \mathit{statement} \begin{bmatrix} \begin{bmatrix} \mathsf{THEN} \end{bmatrix} \mathit{statement} \end{bmatrix} \cdots\\ \end{Bmatrix} \end{Bmatrix}\\ \end{bmatrix}\\ \quad \begin{bmatrix} \mathsf{NOT} \begin{bmatrix} \mathsf{ON} \end{bmatrix} \mathsf{EXCEPTION} \begin{Bmatrix} \mathit{statement} \begin{bmatrix} \begin{bmatrix} \mathsf{THEN} \end{bmatrix} \mathit{statement} \end{bmatrix} \cdots\\ \begin{Bmatrix} \mathit{statement} \begin{bmatrix} \begin{bmatrix} \mathsf{THEN} \end{bmatrix} \mathit{statement} \end{bmatrix} \cdots\\ \end{Bmatrix} \end{Bmatrix}\\ \end{bmatrix}\\ \mathsf{END} \text{-} \mathsf{EXPORT}$