Structure-oriented processing
Processing of a file with organization XML begins with an OPEN statement and ends with a CLOSE statement. In principle such a file contains multiple XML documents. Currently, however, only files which contain precisely one XML document are supported. Processing of this document, in particular generation of the tree presentation for the XML document, begins with an OPEN DOCUMENT statement and ends with a CLOSE DOCUMENT statement. The STARTstatement is used for the purpose of positioning in the XML tree. The READ statement transfers data from one or more nodes of the XML tree to the program. The OPEN DOCUMENT statement with the AT phrase (together with a CLOSE DOCUMENT phrase) enables a subtree to be handled like a separate document.
Event-oriented processing
The XML document to be edited must be made available in memory. The user program is responsible for determining whether a document should be read in from a file if required, whether an encoding should be converted, etc. The XML PARSE statement then edits and parses a complete XML document step by step. As soon as a syntax unit of the document is recognized, control is transferred temporarily to a routine – referred to as the processing procedure – which must be made available by the user and which handles the unit (comparable to the I/O procedures of a SORT statement). The syntax unit detected and additional data which is linked to it are made available in special registers in the processing program for further processing. When the processing program has been completed, the XML statement is resumed. This switching between the XML statement and the processing procedure continues until no further processing is possible as a result of errors, or the user program dispenses with parsing the XML document further.
Data transfer with structure-oriented processing
It is assumed that the XML document is presented in tree form in UTF-16, regardless how it is actually presented. Individual data items in the XML tree are referred to as XML values and must be regarded as elementary items of the national category. Transfer of the data from the XML tree to the receiving items in the COBOL program may therefore also involve conversion. The type of transfer is determined by the length of the XML value and the category of the receiving item.
Length of the XML value = 0:
The receiving item is initialized in accordance with the following statement:INITIALIZE receiving-item TO DEFAULT
- Length of the XML value > 0:
-
The category of the receiving item is national:
The XML value is transferred in accordance with the rules for a MOVE statement.The category of the receiving item is alphabetic or alphanumeric:
The XML value is converted in accordance with the standard function DISPLAY-OF (without a second argument), and the result is transferred in accordance with the rules for a MOVE statement.The category of the receiving item is numeric:
A numeric value is formed from the XML value in accordance with the standard function NUMVAL-C (without a second argument), and this is transferred in accordance with the rules for a MOVE statement.
Exceptional condition in the case of structure-oriented processing
The XML document which is made available in a file or in memory is converted to national character representation in order to generate the tree presentation (in the case of the OPEN DOCUMENT statement without AT phrase). If characters which are not in national (UTF-16) code are found when this is done, the exceptional condition EC-XML-CODESET-CONVERSION occurs. This exceptional condition is NON-FATAL. The replacement character appears in the XML tree in place of the characters concerned.
After an XML value has been transferred to alphanumeric or alphabetic receiving items, the exceptional condition EC-DATA-CONVERSION may occur. The replacement character appears in this case in place of characters which could not be converted. If a USE procedure which is exited using RESUME AT NEXT STATEMENT exists for this exceptional condition, the program run is continued when the next XML value is transferred if multiple XML values are to be transferred using the READ statement and not all of these have been transferred yet.
Nesting statements for processing XML documents
The following restriction applies both for the statements for structure-oriented processing and for the statements for event-oriented processing of XML documents:
Execution of USE procedures or processing procedures while statements for processing an XML document – this can in particular involve the OPEN statement (see chapter "OPEN statement"), the READ statement (see chapter "READ statement") and the XML PARSE statement (see chapter "XML statement") – are being executed may not result in a further such statement being executed.