Rational Developer for System z, Version 7.6

Mapping COBOL tables to repeatable XML data structures

This topic describes which types of mappings the COBOL to XML mapping tools allow you to make between COBOL tables and repeatable XML Schema elements, for both request mappings (mapping a repeatable XML Schema element to a COBOL table) and response mappings (mapping a COBOL table to a repeatable XML Schema element). This topic also describes how these mappings are handled by the runtime environment.
Note: This topic describes only XML Schema elements (typically occurring in a file ending with the extension .xsd) but similar rules apply also to mapped XML elements that occur in XML instance documents (extension .xml) and in WSDL documents (extension .wsdl) (see XML to COBOL mapping concepts).

Common rules for request and response mappings

A "repeatable XML Schema element" is an XML Schema item that has the maxOccurs attribute either set to an integer value that is >= 1 or else set to unbounded.

A COBOL table is a COBOL elementary item or group item that includes in its data description either an OCCURS clause (creating a fixed-length table) or an OCCURS DEPENDING ON clause (creating a variable-length table). In IBM® online help, "ODO" is an abbreviation for OCCURS DEPENDING ON.

Note: The EST tooling environment validates a mapping between a repeatable XML Schema element and a corresponding COBOL table only when you create the mapping in one of the COBOL to XML mapping tools. If you create a valid mapping in the mapping tool and then later modify the repeatable XML Schema element or the corresponding COBOL table so that the mapping is no longer valid, the EST tooling environment does not display an error message, and result of the mapping at run time is unpredictable.
Tip: Therefore, if you modify a mapped XML Schema element or if you modify the corresponding COBOL table, you should verify that the mapping is still valid, or else recreate the mapping in one of the XML to COBOL mapping tools.
The COBOL to XML mapping tools enforce the following rules for both request mappings and response mappings:
  • A repeatable XML Schema element and the corresponding COBOL table occurrence (analogous to an array element) must have structures that are isomorphic. Otherwise, the mapping tool does not permit the mapping.
    Note: Isomorphic means that the two structures contain subelements that have the same data types and that occur in the same order (see Isomorphic and non-isomorphic simple mapping).

    Thus if the COBOL table occurrence is MY-USER-ENTRY and the corresponding repeatable XML Schema element is MyUserEntry, then MY-USER-ENTRY and MyUserEntry must be isomorphic.

  • If the COBOL table is a variable-length table (that is, if the table's data description contains an OCCURS DEPENDING ON clause), then the mapping tools enforce the following rules:
    • In addition to mapping the repeatable XML Schema element to the corresponding COBOL table, then you must also create an XML to COBOL mapping between the COBOL item that is the object of the ODO clause and its corresponding XML Schema element (for a description of the object of the ODO clause, see the appropriate COBOL documentation for the OCCURS DEPENDING ON clause).

      Thus if the object of the ODO clause is NUM-USER-ENTRIES, then you must create a mapping between the COBOL item NUM-USER-ENTRIES and a corresponding XML Schema element (such as an element named NumUserEntries).

    • In the .xsd file, the XML Schema element that corresponds to the COBOL item that is the object of the ODO clause must occur before the repeatable XML Schema element that corresponds to the COBOL table.

      Thus if the COBOL table is named USER-ENTRIES and the object of its ODO clause is the item NUM-USER-ENTRIES, then the XML Schema element that you map to NUM-USER-ENTRIES must appear in the .xsd file before the XML Schema element that you map to USER-ENTRIES.

    Note: The rules for variable-length tables are necessary because of some of the requirements that COBOL imposes on defining data.
  • For multidimensional arrays (also referred to as "nested tables" in COBOL documentation), the XML to COBOL mapping tools enforce the following rules:
    • A repeatable XML Schema element that contains a multidimensional array and the corresponding COBOL nested table to which you are seeking to map the repeated XML Schema element must have the same number of array dimensions.
    • Each array dimension in the XML Schema data structure must contain the same number of elements as the corresponding array dimension in the COBOL nested table, and the elements in each dimension must be isomorphic.
    • A mapping between a single dimension of a multidimensional array in an XML Schema element and a single dimension of a COBOL nested table is not permitted.

Assumptions as to the number of instances

To determine whether a mapping is valid, the XML to COBOL mapping tools make certain assumptions about the maximum number of instances that can occur for a repeatable XML Schema element or for an item in a COBOL table.

Note: These same assumptions are made by a single-service wizard when it is defining data areas within a generated conversion program (either XML to COBOL or COBOL to XML).
The assumptions are as follows:
  • For an repeatable XML Schema element, the maximum number of repetitions of the element that can occur is the integer value stated in the maxOccurs attribute of the element. However, if the maxOccurs attribute is set to unbounded, then special rules apply (see the remaining sections in this help topic).
  • For a fixed-length COBOL table, the maximum number of occurrences of an item that the table can contain is the value stated in the OCCURS clause. For a variable-length COBOL table, the maximum number of occurrences of an item that the table can contain is the maximum value stated in the OCCURS DEPENDING ON clause.

Policy

In determining whether a mapping between a repeatable XML Schema element and a COBOL table is valid, Enterprise Service Tools implements the following policy:
  • The mapping tools are flexible in allowing you to map together two items that potentially can contain different numbers of elements at run time.

    For example, the mapping tools allow you to map a repeatable XML Schema element that can repeat as many as 30 times to a COBOL table that can contain a maximum of only 20 elements. (This examples assume that the XML Schema element is isomorphic with the COBOL table item and that the mapping is otherwise valid).

  • At run time, the generated conversion program checks for an inequality between the actual number of repetitions of the XML Schema element and the actual number of elements that the COBOL table can contain.

    If the conversion program determines that the data cannot be converted (either from XML Schema to COBOL or from COBOL to XML Schema) because the source data contains more elements than are available in the target data structure, then at that time the conversion program returns an error code to the calling program.

Mapping request data

Table 1 shows which types of mappings the COBOL to XML mapping tools allow you to make for request data, and also describes how these mappings are handled by the runtime environment. In this scenario, at run time, the conversion program wants to convert the data contained in the actual number of repetitions of the repeatable XML Schema element into items in the actual COBOL table.
Table 1. COBOL to XML Mapping Request Data
Source data area: Target data area: Maximum possible number of repetitions (See Note) Does the mapping tool permit the mapping? Runtime results:
Repeatable XML Schema element, with maxOccurs set to an integer value. COBOL table LESS THAN OR EQUAL TO.
  • Example: The XML schema element can repeat up to 20 times, whereas the COBOL table can contain up to 30 elements (20 <= 30).
The mapping is permitted. The XML Schema data is converted into occurrences in the COBOL table.
Repeatable XML Schema element, with maxOccurs set to an integer value. COBOL table GREATER THAN.
  • Example: The XML schema element can repeat up to 50 times, whereas the COBOL table can contain only up to 30 elements (50 > 30).
The mapping is not permitted.
  • Normally, the XML Schema data is converted into occurrences in the COBOL table.
  • But if there are more repetitions of the XML Schema element than there are available slots in the COBOL table, then an error is generated at run time.
Repeatable XML Schema element, with maxOccurs= unbounded COBOL table The XML Schema element can repeat any number of times, whereas the COBOL table has a finite maximum number of occurrences.
  • Example: The XML schema element has maxOccurs= unbounded, whereas the COBOL table can contain only up to 30 elements.
The mapping is permitted.
  • Normally, the XML Schema data is converted into occurrences in the COBOL table.
  • But if there are more repetitions of the XML Schema element than there are available slots in the COBOL table, then an error is generated at run time.
Note: When you attempt to do the mapping in the mapping tool, is the maximum possible number of repetitions of the repeatable XML Schema element LESS THAN OR EQUAL TO the maximum possible number of items in the COBOL table?

Mapping response data

Table 2 shows which types of mappings the COBOL to XML mapping tools allow you to make for response data, and also describes how these mappings are handled by the run time environment. In this scenario, at run time, the conversion program wants to convert the data contained in the actual number of COBOL table items into actual repetitions of the repeatable XML Schema element.
Table 2. COBOL to XML Mapping Response Data
Source data area: Target data area: Maximum possible number of repetitions (See Note) Does the mapping tool permit the mapping? Runtime results:
COBOL table Repeatable XML Schema element, with maxOccurs set to an integer value. LESS THAN OR EQUAL TO.
  • Example: The COBOL table can contain up to 30 elements, whereas the XML schema element can repeat up to 50 times (30 <= 50).
The mapping is permitted. The occurrences in the COBOL table are converted into repetitions of the repeatable XML Schema element.
COBOL table Repeatable XML Schema element, with maxOccurs set to an integer value. GREATER THAN.
  • Example: The COBOL table can contain up to 30 element, whereas the XML schema element can repeat only up to 20 times ( 30 > 20).
The mapping is not permitted.
  • Normally, the occurrences in the COBOL table are converted into repetitions of the repeatable XML Schema element.
  • But if there are more occurrences in the COBOL table than there are allowed repetitions of the XML Schema element, then an error is generated at run time.
COBOL table Repeatable XML Schema element, with maxOccurs= unbounded The COBOL table has a finite maximum number of occurrences, whereas the XML Schema element can repeat any number of times.
  • Example: The COBOL table can contain up to 30 elements, whereas the XML schema element has maxOccurs= unbounded.
The mapping is permitted.
  • The occurrences in the COBOL table are converted into repetitions of the repeatable XML Schema element.
Note: When you attempt to do the mapping in the mapping tool, is the maximum possible number of items in the COBOL table LESS THAN OR EQUAL TO the maximum possible number of repetitions of the repeatable XML Schema element?

Terms of use | Feedback

This information center is powered by Eclipse technology. (http://www.eclipse.org)