Function
On the basis of an existing assignment, the READ statement positions to elements or attributes from the XML document, assigns them to the data items in the FD and transfers values associated with them.
Format
READ file-name-1 {ATTRIBUTE | [ONLY] ELEMENT} data-name-1
[AT END imperative-statement-1]
[NOT AT END imperative-statement-2]
[END-READ]
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 and subordinate to the filename-1 file.
If ATTRIBUTE is specified in the READ statement, the ATTRIBUTE phrase must be specified for the IDENTIFIED clause in the data description entry of data-name-1 .
If ELEMENT is specified in the READ statement, the ELEMENT phrase must be specified or implied for the IDENTIFIED clause in the data description entry of data-name-1.
General rules
If the file-name-1 file is not open, the READ statement is not successful. The I-O status of the file is set to 47.
If no XML document is open in the file-name-1 file, the READ statement is not successful. The I-O status of the file is set to 4D.
If data-name-1 does not have a valid position, the READ statement is not successful. The I-O status of the file is set to 46.
The READ statement first performs assignment (see section "Language elements of the DATA DIVISION"), and then transfers data if required. If no node from the XML tree can be assigned in the first step of this assignment procedure, the READ statement is not successful. The I-O status is set to 10, i.e. an at end condition exists.
If the names in the IDENTIFIED clauses which are effective in the assignment are not unique (see section "IDENTIFIED clause", general rule 9), the READ statement is not successful. The I-O status of the file is set to 4C.
If individual attributes or element names from the IDENTIFIED clauses which are effective in the assignment cannot be represented in UTF-16 encoding, the READ statement is not successful. The I-O status of the file is set to 4E.
When assignment takes place, only data item data-name-1 must be taken into consideration in the first step on the COBOL side, then the following nodes in the XML tree:
If data-name-1 is an IDENTIFIED BY clause which has the ATTRIBUTE phrase: the node from the XML tree assigned to data-name-1 and all its siblings. As attributes of an element must be unique in XML documents, the order in which these nodes are to be considered is irrelevant here.
Otherwise:
If the node was assigned to data-name-1 using a READ statement: all younger siblings of this node in the order of the oldest of the younger siblings to the youngest of the younger siblings.
If the node was assigned to data-name-1 using an OPEN DOCUMENT or START statement: this node itself and then all its younger siblings in the order of the oldest of the younger siblings to the youngest of the younger siblings.
If ONLY is specified, the assignments made for all data items which, explicitly or implicitly, have the ELEMENT phrase and which are subordinate to data-name-1 must be interpreted for all READ statements as if they had been specified by means of a START statement (and not using the READ statement).
If, in the subtree of the XML document whose root is the node which was assigned to data-name-1, nodes also exist which could not be assigned to any data item from the COBOL program, and if ONLY is not specified, the READ statement is not successful. The I-O status is set to 08.
As a result of the READ statement, data items in the record description entries of filename-1 e either remain unchanged, or are initialized, or the statement transfers data from the XML tree. In each individual case this depends on the assignment currently implemented and the position of the data items in the record descriptions relative to data-name-1:
Data items
data-name-1 was assigned to a node
data-name-1 was not assigned to a node
data-name-1
Transfer
Unchanged
Data item is subordinate to data-name-1; a node was assigned.
Transfer
– Data item is subordinate to data-name-1; no node was assigned.
Initialization
Unchanged
Other data items
Unchanged
Unchanged
If ONLY is specified, transfer is restricted to data for data-name-1 and all the data items which are directly subordinate to it which have the ATTRIBUTE phrase in their IDENTIFIED clause.
'Transfer' or 'Initialization' in conjunction with a data item means the assignment of values to the following data items (provided these are defined):
Transfer
Initialization
Data item from the USING phrase of the IDENTIFIED clause
Name of the node from the XML tree
Blanks
Data item from the NAMESPACE USING phrase
Value of the namespace from the XML tree
Blanks
Data item for the value
Value of the node from the XML tree
INITIALIZE data-item TO DEFAULT
Data item from the COUNT clause
1
0
For the transfer, data from the XML tree is regarded as an XML value and handled accordingly (see "Data transfer with structure-oriented processing" in section "Language elements of the PROCEDURE DIVISION").The data item for the value of a node corresponds to the data item with the IDENTIFIED clause, if this is elementary. Otherwise it must be directly subordinate to the data item with the IDENTIFIED clause and is the only one of the directly subordinate data items which may neither have an IDENTIFIED clause nor be referenced by an IDENTIFIED clause.
Mixed content values are combined to form a single value. The content of CDATA sections is supplied as a component part of the 'normal values'.
Values are also supplied for attributes which are not specified in the XML document if these are assigned a default value in the DTD.
Whether execution of the READ statement continues depends on whether AT END or NOT AT END is specified, see section "At end condition".