The XML document which is to be processed by a COBOL program can be made available both in a file and in memory (in alphanumeric or national representation) – e.g. in a data item of the LINKAGE-SECTION. In both cases it is handled like a file with the new file organization XML. In the following the term XML file therefore always covers these two options. As for files which already existed, entries in the ENVIRONMENT DIVISION and in the DATA DIVISION are consequently also required for an XML document.
ENVIRONMENT DIVISION
The XML document requires a file control entry in the FILE-CONTROL paragraph:
In addition to the SELECT clause, the ORGANIZATION clause must be specified with the (new) organization XML.
The connection to the medium which contains the XML document is established in the ASSIGN clause.
If the XML document is contained in a file, the same ASSIGN clause is used as usual.
If the XML document is contained in a memory area, you can specify the corresponding data item directly by means of DATA data-name-1.
Alternatively you can use data-name-2 LENGTH data-name-3 to specify a data pointer which points to the memory area containing the XML document in the length (in characters) specified by data-name-3.
The ACCESS MODE clause can be omitted. However, if it is specified, the only permissible access type is XML.
All other clauses are forbidden for an XML document, with the exception of the FILE STATUS clause, whose extended form is permitted. As a result, a return code of the parser is available as a supplement.
The file control entry does not describe any attributes of a specific file for an XML document.
Consequently if the XML document is contained in a file, the entry does not define a file format. Rather, sequential and index-sequential files, POSIX files and also library members are possible. In the case of the index-sequential files the, ISAM key at the beginning (8 bytes) is removed.
Example 12-37 File control entry for an XML document
...
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT xml-doc1 ASSIGN TO "LINK-NAM"
ORGANIZATION IS XML
ACCESS XML.
SELECT xml-doc2 ASSIGN TO DATA w-s-doc
ORGANIZATION IS XML.
SELECT xml-doc3 ASSIGN TO doc-ptr LENGTH doc-lg FOR NATIONAL
ORGANIZATION IS XML.
...
WORKING-STORAGE SECTION.
01 w-s-doc VALUE "<a att="123">xxxx<b>zz<c>9876</c></b></a>".
01 doc-ptr USAGE POINTER.
01 doc-lg PIC 9(8) BINARY.
Comments:
The XML document processed with xml-doc1 is contained in a file with the link name LINK-NAM.
The XML document processed with xml-doc2 is contained in memory in data item w-sdoc. It has the same length as data item w-s-doc.
The XML document processed with xml-doc3 is contained in a memory area in UTF-16 representation (national). Data item doc-ptr points to this memory area, and the length of the document (in characters) is contained in data item doc-lg. You must supply both data items with appropriate values before processing begins.
DATA DIVISION
The XML document requires a data description entry in the FILE SECTION:
All clauses except the EXTERNAL and GLOBAL clauses are forbidden for an XML document.
The 01 record description entries in the FD describe parts of the XML document or the entire document. At least one of the record description entries must describe the root of the document. Multiple record description entries make sense if XML documents with different structures are to be processed with one data description entry or individual record description entries each only describe parts of the document, see also "OPEN DOCUMENT". You may omit individual or all children in the description for each node – regardless of whether elements or attributes are concerned. If no data item for a node in the tree is contained in the record description entry, no node from the corresponding subtree can occur in the record description entry.
Nodes from the document must be described with the new IDENTIFIED clause (see also "Specifying an element or attribute name in the IDENTIFIED clause" in section "COBOL language elements for describing an XML document"). This clause is permitted only in record descriptions of files with organization XML.
The data description entry does not describe attributes of a specific file, but only the logical structure of the XML document.
The 01 record description entries have nothing to do with the presentation of the file in the file administration system or anything similar. For this reason the record description entries in the FD of an XML file do not redefine themselves, as is implicitly the case with sequential, relative and indexed file organization.
If the XML document is contained in a file, any attributes are possible for the records (record format, record length, blocking, character code).
Example 12-38 File description entry for an XML document
...
FILE SECTION.
FD xml-doc2.
01 a IDENTIFIED BY "a".
02 a-value PIC X(10).
02 att IDENTIFIED BY "att"
ATTRIBUTE PIC 999.
02 b1 IDENTIFIED BY "b"
PIC X(10).
01 b2 IDENTIFIED BY "b".
02 b-value PIC X(10).
02 c IDENTIFIED BY "c"
PIC X(10).
...
Comments:
The file description entry refers to the corresponding SELECT clause in example 12-37.
Record description entry a describes the section of the XML document consisting of its root ’a’, its attribute ’att’ and its children ’b’. Record description entry b2 describes the section of the XML document consisting of node ’b’ and this node’s children ’c’.
The overlap of the two 01 structures in node ’b’ means that it is also possible to access grandchildren of root node ’a’ although each of the 01 structures describes only parents and children.