action.skip

XML GENERATE Statement

The XML GENERATE statement converts the data items in identifier-2 into an XML document that is stored in identifier-1.

A converted data element stores the value of the data item, the name of the data element, and XML markup. The element names are derived from the data names in identifier-2.

General Format:

       XML GENERATE identifier-1 FROM identifier-2 [COUNT [IN] identifier-3]
              [[ON] EXCEPTION imperative-statement-1]
              [NOT [ON] EXCEPTION imperative-statement-2]
              [END-XML]

Syntax Rules:

  1. identifier-1 is the data item into which the XML document is generated. identifier-1 must be declared as an elementary or group item of category alphanumeric. identifier-1 must not overlap identifier-2 or identifier-3.
  2. identifier-1 must be large enough to hold the XML document. A commonly used guideline is to give identifier-1 a size that is 5-10 times the size of identifier-2. If identifier-1 is too small, the XML GENERATE statement will produce an error condition.
  3. identifier-2 is the group or elementary item to be converted into an XML document. It must not overlap identifier-1 or identifier-3.
  4. identifier-3 is a numeric data item. It must not overlap identifier-1 or identifier-2.

General Rules:

  1. identifier-1 must not be described with the JUSTIFIED clause, and cannot be a function identifier.
  2. If identifier-1 is larger than the XML document, the trailing bytes will not be altered by the XML Generate operation. Data that was present from a previous GENERATE statement could still be present, and not overwritten. For this reason, it is good practice to INITIALIZE identifier-1 before performing the XML GENERATE statement. Alternatively, you could use identifier-3 as a reference modifier when referring to the data in identifier-1.
  3. identifier-2 cannot be reference modified, and cannot be described with the RENAMES clause.
  4. XML GENERATE will ignore the following in identifier-2:
    • Unnamed elementary data items, or FILLER data items.
    • Slack bytes inserted for SYNCRONIZED items.
    • Any items described with or subordinate to a REDEFINES clause.
    • Any items decribed with the RENAMES clause,
    • Any group item whose subordinate data items are all ignored.
  5. There must be at least one unignored elementary data item in the identifier-2 group item.
  6. Excluding ignored data items, elementary data items in the identifier-2 group item must be CLASS ALPHABETIC, ALPHANUMERIC, NUMERIC, or be an INDEX item.
  7. The COUNT IN phrase manages the count of generated XML characters (in bytes) that are stored in identifier-3.
  8. identifier-3 must be an integer data item without the symbol "P" in its picture string.

ON EXCEPTION phrase

An EXCEPTION condition exists when an error occurs during the generation of the XML document. As an example, if identifier-1 is not large enough to hold the XML document, an EXCEPTION condition will be triggered. When an EXCEPTION condition is triggered, control passes to imperative-statement-1. The contents of identifier-1 are undefined. If a COUNT IN phrase was used, the number of characters generated can be retrieved in identifier-3.

NOT ON EXCEPTION phrase

If the ON EXCEPTION phrase is specified, and no EXCEPTION condition is triggered, then control passes to imperative-statement-2.

END-XML phrase

The END-XML phrase delimits the scope of both XML GENERATE and XML PARSE statements.

Nested XML statements

An XML GENERATE or XML PARSE statement located in an ON EXCEPTION imperative-statement is referred to as a nested (or conditional) XML statement. The scope of a conditional XML GENERATE or XML PARSE statement is terminated by either an END-XML phrase at the same level of nesting, or by a separator period.

Special Registers

See IBM Enterprise COBOL Programming Guide for more information.

XML-CODE

  1. The XML-CODE special register indicates whether an XML GENERATE statement executed successfully or an exception occurred during XML generation. A successful execution of the XML GENERATE statement causes the XML-CODE special register to be set to 0. Exception conditions return non zero error codes to the XML-CODE special register.
  2. The XML CODE special register is implicitly defineds as:

    XML-CODE PICTURE S9(9) USAGE BINARY VALUE 0.

    Details on handling non-zero error codes is detailed in the IBM Enterprise COBOL Programming Guide, in the "Handling XML Parse exceptions" chapter.

Converting data values, and element names

COBOL-IT uses IBM rules for converting elementary data items to character format, for data trimming, and for deriving element names.

Converting elementary data items

Converting elementary data items is the process of translating different data types into a character format. Alphanumeric data values are unchanged. Rules for converting elementary data items are detailed in the IBM Enterprise COBOL Programming Guide.

Data trimming

Data trimming is the application of rules that determine how leading and trailing zeroes, and spaces are handled for a variety of different cases. Rules for applying data trimming are detailed in the IBM Enterprise COBOL Programming Guide.

Element naming

Element naming is the process of translating element data names in identifier-2 into element tag names in the XML document. In most cases, you will see that your element tag name corresponds exactly to yur element name. However, there are cases where data names may contain characters that are illegal in XML. Rules for element naming are detailed in the IBM Enterprise COBOL Programming Guide.