ILE COBOL Language Reference

Operation of XML GENERATE

The content of each eligible elementary data item within identifier-2 is converted to character format as described under Format conversion of elementary data and Trimming of generated XML data. 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.

The converted content is then inserted as element character content in XML markup. The XML element names are derived from the data-names within identifier-2 as described under XML element name formation. The names of group items that contain the selected elementary items are retained as parent elements. No extra white space (new lines, indentation, and so forth) is inserted to make the generated XML more readable. An XML declaration is not generated.

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 (UCS-2 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-2 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. (See also the ILE COBOL Programming Guide for details.)

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.

Format conversion of elementary data

Elementary data items are converted to character format depending on the type of the data item:

After any conversion to character format, leading and trailing spaces and leading zeroes are eliminated, as described under Trimming of generated XML data.

If a data item after any conversion contains any characters that are illegal in XML content, as specified in the relevant XML specification, the original data value (that is, the value in the data item before any conversion or trimming) is represented in hexadecimal, and an element tag name with the prefix 'hex.' is substituted for the regular tag name. For example, if data item Customer-Name is found at run time to contain LOW-VALUES, the XML element tag name 'hex.Customer-Name' is used instead of the normal 'Customer-Name', and the content is represented as a string of pairs of zero digits.

Any remaining instances of the five characters & (ampersand), ' (apostrophe), > (greater-than sign), < (less-than sign), and " (quotation mark) are converted into the equivalent XML references '&amp;', '&apos;', '&gt;', '&lt;', and '&quot;', respectively.

Then, if identifier-1 is a data item of category national, any nonnational values are converted to national format.

Trimming of generated XML data

Trimming is performed on data values after their conversion to character format. (Conversion is described under Format conversion of elementary data.)

For values converted from signed numeric values, the leading space is removed if the value is positive.

For values converted from numeric items, leading zeroes (after any initial minus sign) up to but not including the digit immediately before the actual or implied decimal point are eliminated. Trailing zeroes after a decimal point are retained. For example:

Character values from data items of class alphabetic, alphanumeric, DBCS, and national have either trailing or leading spaces removed, depending on whether the corresponding data items have left (default) or right justification, respectively. That is, trailing spaces are removed from values whose corresponding data items do not specify the JUSTIFIED clause. Leading spaces are removed from values whose data items do specify the JUSTIFIED clause. If a character value consists solely of spaces, one space remains as the value after trimming is finished.


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]