Function
The OPEN DOCUMENT statement opens processing of an XML document. It generates the internal representation of the XML document and executes initial assignment of elements or attributes from the XML document to data items in the FD.
Format
OPEN DOCUMENT file-name-1 [ AT data-name-1 [STACK] ]
[ RETURNING identifier-1 ]
[ AT END imperative-statement-1 ]
[ NOT AT END imperative-statement-2 ]
[ END-OPEN ]
Syntax rules
file-name-1 must be the name of a file with organization XML.
data-name-1 may be qualified.
data-name-1 must be described with an IDENTIFIED clause with an explicit or implicit ELEMENT phrase and subordinate to the file-name-1 file.
identifier-1 must be an alphanumeric or national data item .
If data-name-1 is specified, the AT END and NOT AT END phrases may not be specified.
General rules
If, for file-name-1, processing of an XML document has been started but has not yet been terminated by means of a CLOSE DOCUMENT statement, an implicit CLOSE statement is executed before a CLOSE DOCUMENT statement without a data-name-1 statement is executed.
If the file-name-1 file is not open, the OPEN DOCUMENT statement is not successful. The I-O status is set to 4B.
If data-name-1 was specified but no XML document is open in the file-name-1 file, the OPEN DOCUMENT statement is not successful. The I-O status of the file is set to 4D.
If the XML document which is to be opened is not well-formed, the OPEN DOCUMENT statement is not successful. The I-O status is set to 3A.
If the encoding in which the XML document is represented could not be ascertained (see the "COBOL2000 User Guide" [1], section 10.4 “Encoding identification”), the OPEN DOCUMENT statement is not successful. The I-O status of the file is set to 3D.
If data-name-1 does not have a valid position, the OPEN DOCUMENT statement is not successful. The I-O status of the file is set to 46.
If the file position indicator points to 'end of file', the OPEN DOCUMENT statement is not successful. The I-O status of the file is set to 10.
If the statement is not successful, all positions in the EPV are set to 'invalid'.
If data-name-1 is not specified, the internal representation of the XML document is generated and the file position indicator is set to 'end of file'.
If data-name-1 is specified, the subsequent processing of the XML document is restricted to the subtree whose root is the node assigned to data-name-1.
If STACK is specified, the status of the EPV is ensured by the OPEN DOCUMENT statement, which means that it can be restored again by the next OPEN DOCUMENT statement for file-name-1. However, no recourse can be made to the backed-up EPV status before such a CLOSE DOCUMENT statement is executed.
If STACK is not specified, the status the EPV had before the OPEN DOCUMENT statement is lost.
The OPEN DOCUMENT statement performs assignment (see section "Language elements of the DATA DIVISION"). However, it transfers no data – except for the RETURNING phrase.
If the names in the IDENTIFIED clauses which are effective in the assignment are not unique (see section “IDENTIFIED clause”, general rule 9, on IDENTIFIED clause ), the OPEN DOCUMENT statement is not successful. The I-O status of the file is set to 4C.
If individual attribute or element names from the IDENTIFIED clauses which are effective in the assignment cannot be represented in UTF-16 encoding, the OPEN DOCUMENT statement is not successful. The I-O status of the file is set to 4E.
When assignment takes place, all data items with level number 01 in the record description entries of file-name-1 must be taken into consideration in the first step on the COBOL side. Furthermore, the following node must be considered in the XML tree:
if data-name-1 is not specified: the root node of the entire XML tree.
if data-name-1 is specified: the node from the XML tree assigned to data-name-1.
If RETURNING is specified, the following is transferred to data item identifier-1:
without AT specification, the name of the root element of the XML document.
with AT specification, the name of the element in the XML document which is assigned to data-name-1.
This transfer takes place with every successful OPEN DOCUMENT statement, even if the root element cannot be assigned to any data item in the COBOL description.
Whether execution of the OPEN DOCUMENT statement continues depends on whether AT END or NOT AT END is specified (see section "At end condition").