XML GENERATE statement

• An elementary data item of category alphanumeric
• An alphanumeric group item
• An elementary data item of category national
• A national group item

When identifier-1 references a national group item, identifier-1 is processed as an elementary data item of category national. When identifier-1 references an alphanumeric group item, identifier-1 is treated as though it were an elementary data item of category alphanumeric.

identifier-1 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, identifier-3, codepage (if an identifier), identifier-4, or identifier-5.

identifier-1 must not be a dynamic-length group item or a dynamic-length elementary item.

The generated XML output is encoded as described in the documentation of the ENCODING phrase.

identifier-1 must reference a data item of category national, or the ENCODING phrase must specify 1208, if any of the following statements are true:

• The CODEPAGE compiler option specifies an EBCDIC DBCS code page.
• identifier-4 or identifier-5 references a data item of category national.
• literal-4, literal-5, or literal-6 is of category national.
• The generated XML includes data from identifier-2 for:
  • Any data item of class national or class DBCS
  • Any data item with a DBCS name (that is, a data item whose name consists of DBCS characters)
  • Any data item of class alphanumeric that contains DBCS characters

identifier-1 must be large enough to contain the generated XML document. Typically, it must be from 5 to 10 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 exists at the end of the XML GENERATE statement.

If identifier-2 references a national group item, identifier-2 is processed as a group item. When identifier-2 includes a subordinate national group item, that subordinate item is processed as a group item.

identifier-2 cannot be a function identifier or be reference modified, but it can be subscripted.

identifier-2 must not overlap identifier-1 or identifier-3.

identifier-2 must not be a dynamic-length group item or a dynamic-length elementary item.

The data description entry for identifier-2 must not contain a RENAMES clause.

The following data items that are specified by identifier-2 are ignored by the XML GENERATE statement:

• Any subordinate unnamed elementary data items or elementary FILLER data items
• Any slack bytes inserted for SYNCHRONIZED items
• Any data item subordinate to identifier-2 that is described with the REDEFINES clause or that is subordinate to such a redefining item
• Any data item subordinate to identifier-2 that is described with the RENAMES clause
• Any group data item all of whose subordinate data items are ignored

All data items specified by identifier-2 that are not ignored according to the previous rules 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.
• Any DBCS data-names, when converted to Unicode, must be legal as names in the XML specification, version 1.0. For details about the XML specification, see XML specification.

For example, consider the following data declaration:

01 STRUCT.
  02 STAT PIC X(4).
  02 IN-AREA PIC X(100).
  02 OK-AREA REDEFINES IN-AREA.
    03 FLAGS PIC X.
    03 PIC X(3).
    03 COUNTER USAGE COMP-5 PIC S9(9).
    03 ASFNPTR REDEFINES COUNTER USAGE FUNCTION-POINTER.
    03 UNREFERENCED PIC X(92).
  02 NG-AREA1 REDEFINES IN-AREA.
    03 FLAGS PIC X.
    03 PIC X(3).
    03 PTR USAGE POINTER.
    03 ASNUM REDEFINES PTR USAGE COMP-5 PIC S9(9).
    03 PIC X(92).
  02 NG-AREA2 REDEFINES IN-AREA.
    03 FN-CODE PIC X.
    03 UNREFERENCED PIC X(3).
    03 QTYONHAND USAGE BINARY PIC 9(5).
    03 DESC USAGE NATIONAL PIC N(40).
    03 UNREFERENCED PIC X(12).

The following data items from the previous example can be specified as identifier-2:

• STRUCT, of which subordinate data items STAT and IN-AREA would be converted to XML format. (OK-AREA, NG-AREA1, and NG-AREA2 are ignored because they specify the REDEFINES clause.)
• OK-AREA, of which subordinate data items FLAGS, COUNTER, and UNREFERENCED would be converted. (The item whose data description entry specifies 03 PIC X(3) is ignored because it is an elementary FILLER data item. ASFNPTR is ignored because it specifies the REDEFINES clause.)
• Any of the elementary data items that are subordinate to STRUCT except:
  • ASFNPTR or PTR (disallowed usage)
  • UNREFERENCED OF NG-AREA2 (nonunique names for data items that are otherwise eligible)
  • Any FILLER data items

The following data items cannot be specified as identifier-2:

• NG-AREA1, because subordinate data item PTR specifies USAGE POINTER but does not specify the REDEFINES clause. (PTR would be ignored if it specified the REDEFINES clause.)
• NG-AREA2, because subordinate elementary data items have the nonunique name UNREFERENCED.

identifier-3

The data count field. Must be an integer data item defined without the symbol P in its picture string.

identifier-3 must not overlap identifier-1, identifier-2, codepage (if an identifier), identifier-4, or identifier-5.

codepage

Must be an unsigned integer data item or unsigned integer literal and must represent a valid coded character set identifier (CCSID). Must identify one of the code pages supported for COBOL XML processing as described in The encoding of XML documents in the Enterprise COBOL Programming Guide.

If identifier-1 references a data item of category national, codepage must specify 1200, the CCSID for Unicode UTF-16.

If identifier-1 references a data item of category alphanumeric, codepage must specify 1208 or the CCSID of a supported EBCDIC code page as listed in The encoding of XML documents in the Enterprise COBOL Programming Guide.

If codepage is an identifier, it must not overlap identifier-1 or identifier-3.

If the ENCODING phrase is omitted and identifier-1 is of category national, the document encoding is Unicode UTF-16, CCSID 1200.

If the ENCODING phrase is omitted and identifier-1 is of category alphanumeric, the XML document is encoded using the code page specified by the CODEPAGE compiler option in effect when the source code was compiled.

If the ENCODING phrase is omitted and identifier-1 is of category alphanumeric, the XML document is encoded using the code page specified by the EBCDIC_CODEPAGE environment variable in effect when the source code was compiled.

If identifier-1 is of category national, the encoding declaration has the value UTF-16 (encoding="UTF-16").

If identifier-1 is of category alphanumeric, the encoding declaration is derived from the ENCODING phrase, if specified, or from the CODEPAGE compiler option in effect for the program if the ENCODING phrase is not specified. See the description of the ENCODING phrase for further details.

For an example of the effect of coding the XML-DECLARATION phrase, see Generating XML output in the Enterprise COBOL Programming Guide.

If the XML-DECLARATION phrase is omitted, the generated XML document does not include an XML declaration.

If the TYPE phrase is specified for particular identifiers, the TYPE phrase takes precedence for those identifiers over the WITH ATTRIBUTES phrase.

For an example of the effect of the ATTRIBUTES phrase, see Generating XML output in the Enterprise COBOL Programming Guide.

Use the NAMESPACE-PREFIX phrase to qualify the start and end tag of each element in the generated XML document with a prefix.

If the NAMESPACE-PREFIX phrase is not specified, or if identifier-5 is of length zero or contains all spaces, the namespace specified by the NAMESPACE phrase specifies the default namespace for the document. In this case, the namespace declared on the root element applies by default to each element name in the document, including that of the root element. (Default namespace declarations do not apply directly to attribute names.)

If the NAMESPACE-PREFIX phrase is specified, and identifier-5 is not of length zero and does not contain all spaces, then the start and end tag of each element in the generated document is qualified with the specified prefix. The prefix should therefore preferably be short. When the XML GENERATE statement is executed, the prefix must be a valid XML name, but without the colon (:), as defined in Namespaces in XML 1.0. The prefix can have trailing spaces, which are removed before use.

identifier-4, literal-4; identifier-5, literal-5

identifier-4, literal-4: The namespace identifier, which must be a valid Uniform Resource Identifier (URI) as defined in Uniform Resource Identifier (URI): Generic Syntax.

identifier-5, literal-5: The namespace prefix, which serves as an alias for the namespace identifier.

identifier-4 and identifier-5 must reference data items of category alphanumeric or national.

identifier-4 and identifier-5 must not overlap identifier-1 or identifier-3.

literal-4 and literal-5 must be of category alphanumeric or national, and must not be figurative constants.

For full details about namespaces, see Namespaces in XML 1.0.

For examples that show the use of the NAMESPACE and NAMESPACE-PREFIX phrases, see Generating XML output in the Enterprise COBOL Programming Guide.

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, as detailed in Handling XML GENERATE exceptions in the Enterprise COBOL Programming Guide.

The scope of a conditional XML GENERATE or XML PARSE statement can be terminated by:

• An END-XML phrase at the same level of nesting
• A separator period

END-XML can also be used with an XML GENERATE or XML PARSE statement that does not specify either the ON EXCEPTION or the NOT ON EXCEPTION phrase.

For more information about explicit scope terminators, see Delimited scope statements.