The second format of the OPEN statement (exclusively for XML files) with the DOCUMENT phrase introduces the actual processing of the XML document. It has the following three tasks:
Procuring working memory which accommodates the document’s tree structure.
Generating the tree presentation corresponding to the XML document in this memory.
Executing an initial assignment of the tree to one of the 01 record description entries from the FD.
The assignment procedure begins in the first step on the COBOL side with all data items at level 01 in the FD. On the XML side it begins with the root of the XML document tree. Further assignments are then implemented, as described under "Assignment procedure" in section "Statements for XML processing". |
Positioning (START) and reading (READ) are then possible via successfully positioned data items.
OPEN DOCUMENT also permits AT data-name-1 [STACK] to be specified (here data-name-1 must be defined with an IDENTIFIED clause for element nodes). In contrast to the statement without the AT phrase, which makes a complete XML document available for processing, the AT phrase restricts the (further) processing to a subtree of this document. However, the root of the subtree must have become reachable (by means of preceding statements), i.e. the specified data-name-1 must have a valid position.
The assignment procedure begins in the first step on the COBOL side with all data items at level 01 in the FD, and on the XML side with the root of a subtree. The node assigned to data-name-1 serves as the root. Further assignments are then implemented, as described under "Assignment procedure" in section "Statements for XML processing". |
The STACK phrase causes the status of the EPV to be saved before the OPEN statement is executed and ensures that it can be restored later by means of a CLOSE DOCUMENT statement. Without the STACK phrase the 'old' EPV status is lost.
Example 12-40 OPEN DOCUMENT
XML document | Node | COBOL data structure | OPEN | OPEN |
<a> | 1 | FD xml-fil | | |
Comments:
Information on the presentation of this example is provided on Statements for XML processing.
After the first OPEN DOCUMENT statement, data item y has a valid position and can therefore be used in the AT phrase in the second OPEN DOCUMENT statement.
The assignment procedure in the second OPEN DOCUMENT statement includes all 01 structures, but only regards the subtree with node 3 as a root. This results in invalid positions for data items x and y.
As no STACK phrase was specified, only the valid positions in the EPV are available for further accesses, i.e. the root of the XML document (node 1) can no longer be reached by the subsequent statement unless the document and the file are closed and opened again.
Summary
In summary, the following must be observed in the case of the OPEN DOCUMENT statement:
Access to an XML document always begins at its root. Consequently the OPEN DOCUMENT statement without AT phrase must always be executed first. Even the specification of the root as an identifier in the AT phrase does not work, because this requires the specified data item to have a valid position.
OPEN DOCUMENT with an AT phrase but without a STACK phrase corresponds to a movement in the tree from the root toward the leaves without the option of reversing it.
The COBOL record structures are actually only templates which describe sections of the tree. Starting from the root of the tree they can be made to cover any parts of the tree provided they match at runtime in at least one node, the data item from the AT phrase.
One CLOSE DOCUMENT statement alone is not sufficient to open the same document a second time. For this purpose the file must also be closed and opened again.
OPEN DOCUMENT modifies the EPV only, but leaves data unchanged .