
The XML GENERATE Statement
The XML GENERATE statement converts data to XML format.
General Format

Syntax Rules
- 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.
- Identifier-1 can be subscripted or reference modified.
- Identifier-1 must not overlap identifier-2 or identifier-3.
- Identifier-1 must be a national data item if the generated XML
includes data from identifier-2 for:
- Any national data item or DBCS data item
- Any data item with a DBCS name (that is, a data item whose
name contains DBCS characters)
- An alphanumeric data item that contains DBCS characters
- Identifier-2 cannot be a function identifier or be reference
modified.
- Identifier-2 can be subscripted.
- Identifier-2 must not overlap with identifier-1 or
identifier-3.
- Identifier-2 must not specify the RENAMES clause.
- All data items specified by identifier-2 that are not ignored
according to
General Rule
5 must satisfy the following conditions:
- 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.
- There must be at least one such elementary data item.
- Each non-FILLER data-name must be unique within any
immediately superordinate group data item.
- Identifier-3 must be an integer data item defined without the
symbol P in its picture string.
- Identifier-3 must not overlap identifier-1 or identifier-2.
General Rules
- Identifier-1 is the receiving area for a generated XML document.
- If identifier-1 is a national data item, the generated XML
document is encoded in UTF-16.
- 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.
- Identifier-2 is the group or elementary data item to be converted
to XML format.
- The following data items specified by
identifier-2 are ignored by the XML GENERATE statement:
- Unnamed elementary data items or elementary FILLER data
items
- Slack bytes inserted for SYNCHRONIZED items
- Data items subordinate to identifier-2 that are described
with the REDEFINES clause or that are subordinate to such a redefining
item
- Data items subordinate to identifier-2 that are described
with the RENAMES clause
- Group data items all of whose subordinate data items are
ignored
- 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. The exact mixed-case spelling of data names from the data description
entry is retained and data names that start with a digit are prefixed by an
underscore.
- Elementary data items are converted to
character format depending on the type of the data item:
- Alphabetic, alphanumeric, alphanumeric-edited, DBCS,
external floating-point, national, and numeric-edited items are not
converted.
- 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
- 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
- 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
- Index data items are converted as if they were declared
USAGE COMP-5 PICTURE S9(9).
- If identifier-1 is a national data item, any non-national
values are converted to national format.
- After any conversion to character format, leading and trailing
spaces and leading zeroes are eliminated as follows:
- 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:
- -012.340 becomes -12.340
- 0000.45 becomes 0.45
- 0013 becomes 13
- 0000 becomes 0
- 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.
- 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.
- 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
&, ',
>, <, and
", respectively.
- 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 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.
- 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.
- 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.