Function
The XML GENERATE statement converts data to an XML document.
Format
XML GENERATE data-name-1
FROM data-name-2
[COUNT [IN] data-name-3]
[ON EXCEPTION imperative-statement-1]
[NOT ON EXCEPTION imperative-statement-2]
[END-XML]
Syntax rules
- The output operand data-name-1 is designated for the generated XML document.
- The group or elementary data item data-name-2 is to be converted to the XML document.
- The output operand data-name-3 contains the count of generated XML characters.
- The operands data-name-1, data-name-2 and data-name-3 must not overlap each other.
General rules
- The output operand data-name-1 must be large enough to contain the generated XML document and can reference one of the following:
- elementary or group item of category alphanumeric;
- elementary or group item of category national.
If data-name-1 is of category national, the generated XML document is encoded in UTF-16, otherwise in EBCDIC.
The sending operand data-name-2 must not be described with the RENAMES clause.
The following data items specified by data-name-2 are ignored by the XML GENERATE statement:
- Any unnamed or FILLER data item with its subordinates.
- Any elementary data item that assumes a pointer, e.g. USAGE POINTER, OBJECT REFERENCE etc.
- Any data item (with its subordinates) subordinate to data-name-2 that is described with the REDEFINES clause.
- Any group item (with its subordinates) subordinate to data-name-2 that contains a non-unique name within the same level.
- Any group item that does not contain at least one elementary data item of category alphabetic, alphanumeric, numeric, national or index.
- The output operand data-name-3 must be an integer data item and normally contains a length of the generated XML document in bytes. But if data-name-1 is of category national, the count data-name-3 is in national characters (UTF-16 encoding units).
After execution of the XML GENERATE statement, the special register XML-CODE contains either zero, which indicates successful completion, or a non-zero exception code.
CODE
Description
0
The receiver contains the successfully generated XML document. The COUNT [IN] data item contains the count of character positions in the generated XML document.
400
The receiver is too small to contain the generated XML document. The COUNT [IN] data item contains the count of character positions that were actually generated.
2999
COBOL2000 internal error. No data returned.
- If an error (XML-CODE # 0) occurs during generation of the XML document, control is passed to the conditional statement imperative-statement-1. If ON EXCEPTION is not specified control is passed to the end of the XML GENERATE statement.
- If no error (XML-CODE = 0) occurs during generation of the XML document, control is passed to the conditional statement imperative-statement-2. If NOT ON EXCEPTION is not specified control is passed to the end of the XML GENERATE statement.
- While creating the XML document XML GENERATE observes the following rules:
- The content of each elementary data item within data-name-2 is converted to character format.Trailing spaces and leading zeroes are eliminated.
- Any remaining instances of the five special characters & (ampersand), ’ (apostrophe), > (greater-than sign), < (less-than sign), and “ (quotation mark) are converted into the equivalent XML references ’&’, ’'’, ’>’, ’<’, and ’"’, respectively.
- The transformed content is then inserted as element character content in XML markup.
- The XML element names are derived from the data-name-2 source description. The names of group items are retained as XML parent names
- If data-name-1 is national, any non-national data is converted to national (UTF16) format and vice versa, if data-name-1 is non-national, any national data is converted to alphanumeric (EBCDIC) format.
- The XML declaration (header) is not generated. No extra white space, new line, etc. is inserted to make the generated XML more readable.