Rational Developer for System z
COBOL for Windows, Version 7.5, Language Reference


XML GENERATE statement

The XML GENERATE statement converts data to XML format.

Format
Read syntax diagramSkip visual syntax diagram>>-XML GENERATE--identifier-1--FROM--identifier-2--------------->
 
>--+-----------------------------+------------------------------>
   '-COUNT--+----+--identifier-3-'  
            '-IN-'                  
 
>--+-------------------------------------------+---------------->
   '-+----+--EXCEPTION--imperative-statement-1-'  
     '-ON-'                                       
 
>--+------------------------------------------------+----------->
   '-NOT--+----+--EXCEPTION--imperative-statement-2-'  
          '-ON-'                                       
 
>--+---------+-------------------------------------------------><
   '-END-XML-'  
 
identifier-1
The receiving area for a generated XML document. identifier-1 must reference one of the following:

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 or identifier-3.

If identifier-1 references a data item of category alphanumeric, the code pages indicated by the compile-time locale and the runtime locale must be identical.

If identifier-1 references a data item of category alphanumeric, the generated XML document is encoded with the following code page:

If identifier-1 references a data item of category national, the generated XML document is encoded in UTF-16. A byte order mark is not generated.

identifier-1 must reference a data item of category national if the code page in effect for identifier-1 is a multibyte code page or if the generated XML includes data from identifier-2 for:

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 exists at the end of the XML GENERATE statement.

identifier-2
The group or elementary data item to be converted to XML format.

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 with identifier-1 or identifier-3.

identifier-2 must not specify the RENAMES clause.

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

All data items specified by identifier-2 that are not ignored according to the rules above must satisfy the following conditions:

For example, given 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 can be specified as identifier-2:

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

COUNT IN
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) has category national, the count is in national character positions (UTF-16 character encoding units). Otherwise, the count is in bytes.
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 or identifier-2.

 

 
ON EXCEPTION
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, as detailed in the COBOL for Windows Programming Guide.

 

NOT ON EXCEPTION
If an exception condition does not occur during generation of the XML document, control is passed to imperative-statement-2, if specified, otherwise 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.

 

END-XML phrase
This explicit scope terminator delimits the scope of XML GENERATE or XML PARSE statements. END-XML permits a conditional XML GENERATE or XML PARSE statement (that is, an XML GENERATE or XML PARSE statement that specifies the ON EXCEPTION or NOT ON EXCEPTION phrase) to be nested in another conditional statement.

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

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 on explicit scope terminators, see Delimited scope statements.

Nested XML GENERATE or XML PARSE statements

When a given XML GENERATE or XML PARSE statement appears as imperative-statement-1 or imperative-statement-2, or as part of imperative-statement-1 or imperative-statement-2 of another XML GENERATE or XML PARSE statement, that given XML GENERATE or XML PARSE statement is a nested XML GENERATE or XML PARSE statement.

Nested XML GENERATE or XML PARSE statements are considered to be matched XML GENERATE and END-XML, or XML PARSE and END-XML combinations proceeding from left to right. Thus, any END-XML phrase that is encountered is matched with the nearest preceding XML GENERATE or XML PARSE statement that has not been implicitly or explicitly terminated.

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 (UTF-16 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 COBOL for Windows 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.

Any remaining Unicode character represented by two UTF-16 encoding units (a ”surrogate pair“) is replaced by an XML character reference. For example, the surrogate pair (NX'D802', NX'DC13') is replaced by the reference '&#x10813;'.

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.

XML element name formation

In the XML documents that are generated from identifier-2, the XML element tag names are derived from the name of the data item specified by identifier-2 and from any eligible data-names that are subordinate to identifier-2 as follows:

Multibyte data-names, when translated to Unicode, must be legal as names in the XML specification, version 1.0.

For a discussion of the exception codes that special register XML-CODE can contain after execution of the XML GENERATE statement, see the COBOL for Windows Programming Guide.


Terms of use | Feedback

Copyright IBM Corporation 1996, 2008.
This information center is powered by Eclipse technology. (http://www.eclipse.org)