Variable arrays of elements

XML can contain an array with varying numbers of elements. In general, WSDL documents and XML schemas that contain varying numbers of elements do not map efficiently into a single high-level language data structure. CICS® uses container-based mappings or inline mappings to handle varying numbers of elements in XML.

An array with a varying number of elements is represented in the XML schema by using the minOccurs and maxOccurs attributes on the element declaration:

The minOccurs attribute specifies the minimum number of times that the element can occur. It can have a value of 0 or any positive integer.
The maxOccurs attribute specifies the maximum number of times that the element can occur. It can have a value of any positive integer greater than or equal to the value of the minOccurs attribute. It can also take a value of unbounded, which indicates that no upper limit applies to the number of times the element can occur.
The default value for both attributes is 1.

This example denotes an 8-byte string that is optional; that is, it can occur never or once in the application XML or SOAP message:

<xsd:element name="component" minOccurs="0" maxOccurs="1">
  <xsd:simpleType>
    <xsd:restriction base="xsd:string">
      <xsd:length value="8"/>
    </xsd:restriction>
  </xsd:simpleType>
</xsd:element>

The following example denotes an 8-byte string that must occur at least once:

<xsd:element name="component" minOccurs="1" maxOccurs="unbounded">
  <xsd:simpleType>
    <xsd:restriction base="xsd:string">
      <xsd:length value="8"/>
    </xsd:restriction>
  </xsd:simpleType>
</xsd:element>

In general, WSDL documents that contain varying numbers of elements do not map efficiently into a single high-level language data structure. Therefore, to handle these cases, CICS uses a series of connected data structures that are passed to the application program in a series of containers. These structures are used as input and output from the application:

When CICS transforms XML to application data, it populates these structures with the application data and the application reads them.
When CICS transforms the application data to XML, it reads the application data in the structures that have been populated by the application.

The format of these data structures is best explained with a series of examples. The XML can be from a SOAP message or from an application. These examples use an array of simple 8-byte fields. However, the model supports arrays of complex data types and arrays of data types that contain other arrays.

Fixed number of elements

The first example illustrates an element that occurs exactly three times:

<xsd:element name="component" minOccurs="3" maxOccurs="3">
  <xsd:simpleType>
    <xsd:restriction base="xsd:string">
      <xsd:length value="8"/>
    </xsd:restriction>
  </xsd:simpleType>
</xsd:element>

In this example, because the number of times that the element occurs is known in advance, it can be represented as a fixed-length array in a simple COBOL declaration (or the equivalent in other languages):

05 component PIC X(8) OCCURS 3 TIMES

Varying number of elements at mapping level 2 and below

This example illustrates a mandatory element that can occur from one to five times:

<xsd:element name="component" minOccurs="1" maxOccurs="5">
  <xsd:simpleType>
    <xsd:restriction base="xsd:string">
      <xsd:length value="8"/>
    </xsd:restriction>
  </xsd:simpleType>
</xsd:element>

The main data structure contains a declaration of two fields. When CICS transforms the XML to binary data, the first field component-num contains the number of times that the element appears in the XML, and the second field, component-cont, contains the name of a container:

05 component-num PIC S9(9) COMP-5
05 component-cont PIC X(16)

A second data structure contains the declaration of the element itself:

01 DFHWS-component
  02 component PIC X(8)

You must examine the value of component-num (which will contain a value in the range 1 to 5) to find out how many times the element occurs. The element contents are in the container named in component-cont; the container holds an array of elements, where each element is mapped by the DFHWS-component data structure.

If minOccurs="0" and maxOccurs="1", the element is optional. To process the data structure in your application program, you must examine the value of component-num:

If it is zero, the message has no component element and the contents of component-cont is undefined.
If it is one, the component element is in the container named in component-cont.

The contents of the container are mapped by the DFHWS-component data structure.

Note: If the SOAP message consists of a single recurring element, DFHWS2LS generates two language structures. The main language structure contains the number of elements in the array and the name of a container which holds the array of elements. The second language structure maps a single instance of the recurring element.

Varying number of elements at mapping level 2.1 and above

At mapping level 2.1 and above, you can use the INLINE-MAXOCCURS-LIMIT parameter in the CICS assistants. The INLINE-MAXOCCURS-LIMIT parameter specifies the way that varying numbers of elements are handled. The mapping options for varying numbers of elements are container-based mapping, described in Varying number of elements at mapping level 2 and below, or inline mapping. The value of this parameter can be a positive integer in the range 0 - 32767:

The default value of INLINE-MAXOCCURS-LIMIT is 1, which ensures that optional elements are mapped inline.
A value of 0 for the INLINE-MAXOCCURS-LIMIT parameter prevents inline mapping.
If maxOccurs is less than or equal to the value of INLINE-MAXOCCURS-LIMIT, inline mapping is used.
If maxOccurs is greater than the value of INLINE-MAXOCCURS-LIMIT, container-based mapping is used.

Mapping varying numbers of elements inline results in the generation of both an array, as happens with the fixed occurrence example above, and a counter. The component-num field indicates how many instances of the element are present, and these are pointed to by the array. For the example shown in Varying number of elements at mapping level 2 and below, when INLINE-MAXOCCURS-LIMIT is less than or equal to 5, the generated data structure is like this:

05 component-num PIC S9(9) COMP-5 SYNC. 
05 component OCCURS 5 PIC X(8).

The first field, component-num, is identical to the output for the container-based mapping example in the previous section. The second field contains an array of length 5 which is large enough to contain the maximum number of elements that can be generated.

Inline mapping differs from container-based mapping, which stores the number of occurrences of the element and the name of the container where the data is placed, because it stores all the data in the current container. Storing the data in the current container will generally improve performance and make inline mapping preferable.

Nested variable arrays

Complex WSDL documents and XML schemas can contain variably recurring elements, which in turn contain variably recurring elements. In this case, the structure described extends beyond the two levels described in the examples.

This example illustrates an optional element called <component2> that is nested in a mandatory element called <component1>, where the mandatory element can occur from one to five times:

<xsd:element name="component1" minOccurs="1" maxOccurs="5">
  <xsd:complexType>
    <xsd:sequence>
      <xsd:element name="component2" minOccurs="0" maxOccurs="1">
        <xsd:simpleType>
          <xsd:restriction base="xsd:string">
            <xsd:length value="8"/>
          </xsd:restriction>
        </xsd:simpleType>
      </xsd:element>
    </xsd:sequence> 
  </xsd:complexType>
</xsd:element>

The top-level data structure is exactly the same as in the previous examples:

05 component1-num PIC S9(9) COMP-5
05 component1-cont PIC X(16)

However, the second data structure contains these elements:

01 DFHWS-component1
  02 component2-num PIC S9(9) COMP-5
  02 component2-cont PIC X(16)

A third-level structure contains these elements:

01 DFHWS-component2
  02 component2 PIC X(8)

The number of occurrences of the outermost element <component1> is in component1-num.

The container named in component1-cont contains an array with that number of instances of the second data structure DFHWS-component1.

Each instance of component2-cont names a different container, each of which contains the data structure mapped by the third-level structure DFHWS-component2.

To illustrate this structure, consider the fragment of XML that matches the example:

<component1><component2>string1</component2></component1>
<component1><component2>string2</component2></component1>
<component1></component1>

<component1> occurs three times. The first two each contain an instance of <component2>; the third instance does not.

In the top-level data structure, component1-num contains a value of 3. The container named in component1-cont has three instances of DFHWS-component1:

In the first, component2-num has a value of 1, and the container named in component2-cont holds string1.
In the second, component2-num has a value of 1, and the container named in component2-cont holds string2.
In the third, component2-num has a value of 0, and the contents of component2-cont are undefined.

In this instance, the complete data structure is represented by four containers in all:

The root data structure in container DFHWS-DATA
The container named in component1-cont
Two containers named in the first two instances of component2-cont

Optional structures and xsd:choice

DFHWS2LS and DFHSC2LS support the use of maxOccurs and minOccurs on <xsd:sequence>, <xsd:choice>, and <xsd:all> elements only at mapping level 2.1 and above, where the minOccurs and maxOccurs attributes are set to minOccurs="0" and maxOccurs="1".

The assistants generate mappings that treat these elements as though each child element in them is optional. When you implement an application with these elements, ensure that invalid combinations of options are not generated by the application. Each of the elements has its own count field in the generated languages structure, these fields must either all be set to "0" or all be set to"1". Any other combination of values is invalid, except for with <xsd:choice> elements.

<xsd:choice> elements indicate that only one of the options in the element can be used. It is supported at all mapping levels. The assistants handle each of the options in an <xsd:choice> as though it is in an <xsd:sequence> element with minOccurs="0" and maxOccurs="1". Take care when you implement an application using the <xsd:choice> element to ensure that invalid combinations of options are not generated by the application. Each of the elements has its own count field in the generated languages structure, exactly one of which must be set to '1' and the others must all be set to '0'. Any other combination of values is invalid, except when the <xsd:choice> element is itself optional, in which case it is valid for all the fields to be set to '0'.