ENTMF The XML GENERATE Statement

The XML GENERATE statement converts data to XML format.

General Format
Syntax Rules
  1. Identifier-1 must be an alphanumeric or national data item. It must not be described with the JUSTIFIED clause, and cannot be a function identifier.
  2. Identifier-1 can be subscripted or reference modified.
  3. Identifier-1 must not overlap identifier-2 or identifier-3.
  4. Identifier-1 must be a national data item if the generated XML includes data from identifier-2 for:
    1. Any national data item or DBCS data item
    2. Any data item with a DBCS name (that is, a data item whose name contains DBCS characters)
    3. An alphanumeric data item that contains DBCS characters
  5. Identifier-2 cannot be a function identifier or be reference modified.
  6. Identifier-2 can be subscripted.
  7. Identifier-2 must not overlap with identifier-1 or identifier-3.
  8. Identifier-2 must not specify the RENAMES clause.
  9. All data items specified by identifier-2 that are not ignored according to General Rule 5 must satisfy the following conditions:
    1. Each elementary data item must either have class alphabetic, alphanumeric, numeric, or national, or be an index data item. That is, no elementary data item can be described with the USAGE POINTER, USAGE FUNCTION-POINTER, USAGE PROCEDURE-POINTER, or USAGE OBJECT REFERENCE phrase.
    2. There must be at least one such elementary data item.
    3. Each non-FILLER data-name must be unique within any immediately superordinate group data item.
  10. Identifier-3 must be an integer data item defined without the symbol P in its picture string.
  11. Identifier-3 must not overlap identifier-1 or identifier-2.
General Rules
  1. Identifier-1 is the receiving area for a generated XML document.
  2. If identifier-1 is a national data item, the generated XML document is encoded in UTF-16.
  3. Identifier-1 must be large enough to contain the generated XML document. Typically, it should be from five to eight times the size of identifier-2, depending on the length of the data name or data names within identifier-2. If identifier-1 is not large enough, an error condition occurs at the end of the XML GENERATE statement.
  4. Identifier-2 is the group or elementary data item to be converted to XML format.
  5. The following data items specified by identifier-2 are ignored by the XML GENERATE statement:
    1. Unnamed elementary data items or elementary FILLER data items
    2. Slack bytes inserted for SYNCHRONIZED items
    3. Data items subordinate to identifier-2 that are described with the REDEFINES clause or that are subordinate to such a redefining item
    4. Data items subordinate to identifier-2 that are described with the RENAMES clause
    5. Group data items all of whose subordinate data items are ignored
  6. The content of each eligible elementary data item within identifier-2 is converted to character format as described in General Rule 7. 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. The names of group items that contain the selected elementary items are retained as parent elements. No extra white space (new lines, indentation, etc.) is inserted to make the generated XML more readable. Data names that start with a digit are prefixed by an underscore.

    Note: The exact mixed-case spelling of data names from the data description entry is retained only if you specify the PRESERVECASE directive.

  7. Elementary data items are converted to character format depending on the type of the data item:
    1. Alphabetic, alphanumeric, alphanumeric-edited, DBCS, external floating-point, national, and numeric-edited items are not converted.
    2. Fixed-point numeric data items other than COMPUTATIONAL-5 (COMP-5) binary data items are converted as if they were moved to a numeric-edited item that has:
      • As many integer positions as the numeric item has, but with at least one integer position
      • An explicit decimal point, if the numeric item has at least one decimal position
      • The same number of decimal positions as the numeric item
      • A leading '-' picture symbol if the data item is signed
    3. COMPUTATIONAL-5 (COMP-5) binary data items are converted in the same way as the other fixed-point numeric items except for the number of integer positions. The number of integer positions is computed depending on the number of '9' symbols in the picture character string as follows:
      • 5 minus the number of decimal places, if the data item has one to four '9' picture symbols
      • 10 minus the number of decimal places, if the data item has five to nine '9' picture symbols
      • 20 minus the number of decimal places, if the data item has 10 to 18 '9' picture symbols
    4. Internal floating-point data items are converted as if they were moved to a data item as follows:
      • For COMP-1: an external floating-point data item with PICTURE -9.9(8)E+99
      • For COMP-2: an external floating-point data item with PICTURE -9.9(17)E+99
    5. Index data items are converted as if they were declared USAGE COMP-5 PICTURE S9(9).
    6. If identifier-1 is a national data item, any non-national values are converted to national format.
  8. After any conversion to character format, leading and trailing spaces and leading zeroes are eliminated as follows:
    1. For values converted from signed numeric values, the leading space is removed if the value is positive.
    2. 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:
      • -012.340 becomes -12.340
      • 0000.45 becomes 0.45
      • 0013 becomes 13
      • 0000 becomes 0
    3. Character values from alphabetic, alphanumeric, DBCS, and national data items 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 only of spaces, one space remains as the value after trimming is finished.
  9. If a data item after any conversion contains any characters that are illegal in XML content, the original data value - 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 My-Name is found at run time to contain LOW-VALUES, the XML element tag name hex.My-Name is used instead, and the content is represented as a string of pairs of zero digits.
  10. If a data item after any conversion contains instances of any of the following the five symbols:
    • & (ampersand)
    • ' (apostrophe)
    • > (greater-than sign)
    • < (less-than sign)
    • " (quotation mark)

    the symbols are converted into the equivalent XML references &amp;, &apos;, &gt;, &lt;, and &quot;, respectively.

  11. 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.
  12. If the COUNT IN phrase is specified, identifier-3 contains (after execution of the XML GENERATE statement) the count of generated XML character positions. If identifier-1 (the receiver) is a national data item, the count is in national character positions (UTF-16 character encoding units). Otherwise, the count is in bytes.
  13. An exception condition exists when an error occurs during generation of the XML document, for example if identifier-1 is not large enough to contain the generated XML document. In this case, XML generation stops and the content of the receiver, identifier-1, is undefined. If the COUNT IN phrase is specified, identifier-3 contains the number of character positions that were generated, which can range from 0 to the length of identifier-1. If the ON EXCEPTION phrase is specified, control is transferred to imperative-statement-1. If the ON EXCEPTION phrase is not specified, the NOT ON EXCEPTION phrase, if any, is ignored and control is transferred to the end of the XML GENERATE statement. Special register XML-CODE contains an exception code.
  14. If an exception condition does not occur during generation of the XML document, control is passed to imperative-statement-2, if specified. Otherwise, it is passed to the end of the XML GENERATE statement. The ON EXCEPTION phrase, if specified, is ignored. Special register XML-CODE contains zero after execution of the XML GENERATE statement.