The XML GENERATE statement generates an XML document from existing, COBOL data (i.e., it translates COBOL data to XML format). It is an implementation of the IBM Enterprise COBOL verb of the same name and is provided to simplify IBM migrations; however, any customer wishing to write XML data can use this verb. See Working with Non-Vision Data in A Guide to Interoperating with ACUCOBOL-GT for additional information on working with XML data.
XML GENERATE identifier-1 FROM identifier-2 [COUNT [IN] identifier-3] [[ON] EXCEPTION imperative-statement-1] [NOT [ON] EXCEPTION imperative-statement-2] [END-XML]
If the ON EXCEPTION phrase is specified, control is transferred to imperative-statement-1. If it is not specified, NOT ON EXCEPTION phrases are ignored, and control is transferred to the end of the XML GENERATE statement.
At termination of an XML GENERATE statement, special register XML-CODE contains either 0, indicating successful completion of XML generation, or a non-zero error code, indicating that an exception occurred during XML generation. Following are the possible exception codes that you may encounter:
|The receiver was too small to contain the generated XML document. The COUNT IN data item, if specified, contains the count of character positions that were actually generated.
|600 â€“ 699
|Internal error. Please report the error to your customer support analyst.
The scope of a conditional XML GENERATE or XML PARSE statement is terminated by:
Eligible elementary data items in identifier-2 are converted to character format. (See Data conversion and Data trimming for details.) Only the first definition of each storage area is processed. Redefinitions are not included, nor are data items that are effectively defined by the RENAMES clause.
Once the data content is converted, it is inserted as element character content in XML markup. The XML element names are derived from the data-names in identifier-2. (See Element naming for more information.) The names of group items that contain the selected elementary items are retained as parent elements. No extra white space 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 arises. See the ON EXCEPTION phrase, General Rule #4, for details.
Use the COUNT IN phrase to determine the total number of character positions, in bytes, that were generated. identifier-3 will then contain this information after XML GENERATE executes. 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, indicating successful completion, or a non-zero exception code.
Please note that 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.
How elementary data items are converted to character format depends on the type of data item:
For COMPUTATIONAL-5 (COMP-5) binary data items, the number of integer positions depends on the number of '9' symbols in the picture character string. If the data item has one to four '9' picture symbols, the number of integer positions is five minus the number of decimal places. If the data item has five to nine '9' picture symbols, the number of integer positions is ten minus the number of decimal places. If the data item has 10 to 18 '9' picture symbols, the number of integer positions is 20 minus the number of decimal places.
All other fixed-point numeric data items will have as many integer positions as the numeric item, but with at least one integer position.
After conversion, if a data item contains characters that are illegal in XML, the value in the data item before 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 '&', ''', '>', '<', and '"', respectively.
Data values are trimmed after they are converted to character format. (Conversion is described under Data conversion.) Values converted from signed numeric values have their leading space removed if the value is positive. Values converted from numeric items have leading zeroes eliminated (after any initial minus sign). This is up to but not including the digit immediately before the actual or implied decimal point. Trailing zeroes after a decimal point are retained. For example:
Character values from alphabetic, alphanumeric data items have either trailing or leading spaces removed, depending on whether the corresponding data items have left or right justification, respectively--left being the default. 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, all spaces are removed but one.
The element tag names in the XML documents generated from identifier-2 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. The following rules apply:
When a given XML GENERATE 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 statement, that given XML GENERATE statement is a nested XML GENERATE statement.
Nested XML GENERATE statements are considered to be matched XML GENERATE and END-XML combinations proceeding from left to right. For this reason, when END-XML phrases are encountered, they are matched with the nearest preceding XML GENERATE statements that have not already been terminated.