Operation of XML GENERATE
The content of
each eligible elementary data item within identifier-2 that
has not been suppressed from XML generation according to a SUPPRESS
phrase,
is converted to character format.
Only the first definition of each storage area is processed. Redefinitions of data items are not included. Data items that are effectively defined by the RENAMES clause are also not included.
For information about the format conversion of elementary data, see Format conversion of elementary data and Trimming of generated XML data.
If the TYPE OF phrase is specified, the converted content is then processed as element character content or attribute value, according to the specifications on that phrase. If the TYPE OF phrase is not specified, by default the converted content is inserted as element character content, or, if the WITH ATTRIBUTES phrase is specified and the data item is eligible to be expressed as an attribute, as the value of the attribute, in the generated XML document.
The XML element names and attribute names are obtained from the NAME phrase if specified; otherwise by default they are derived from the data-names within identifier-2 as described in XML element name and attribute name formation. The names of group items that contain the selected elementary items are retained as parent elements. If the NAMESPACE-PREFIX phrase is specified, the prefix value, minus any trailing spaces, is used to qualify the start and end tag of each element.
No extra white space (new lines, indentation, and so forth) is inserted to make the generated XML more readable. An XML declaration is generated if the XML-DECLARATION phrase is specified.
If the receiving area specified by identifier-1 is not large enough to contain the resulting XML document, an error condition exists. See the description of the ON EXCEPTION phrase above for details.
If identifier-1 is longer than the generated XML document, only that part of identifier-1 in which XML is generated is changed. The rest of identifier-1 contains the data that was present before this execution of the XML GENERATE statement. To avoid referring to that data, either initialize identifier-1 to spaces before the XML GENERATE statement or specify the COUNT IN phrase.
If the COUNT IN phrase is specified, identifier-3 contains (after execution of the XML GENERATE statement) the total number of character positions (UTF-16 encoding units or bytes) that were generated. You can use identifier-3 as a reference modification length field to refer to the part of identifier-1 that contains the generated XML document.
After execution of the XML GENERATE statement, special register XML-CODE contains either zero, which indicates successful completion, or a nonzero exception code. For details, see Handling XML GENERATE exceptions in the Enterprise COBOL Programming Guide.
The XML PARSE statement also uses special register XML-CODE. Therefore if you code an XML GENERATE statement in the processing procedure of an XML PARSE statement, save the value of XML-CODE before that XML GENERATE statement executes and restore the saved value after the XML GENERATE statement terminates.
A byte order mark is not generated for XML documents that have Unicode encoding.