Variable arrays of elements

A SOAP message can contain an array with varying numbers of elements. An array with a varying number of elements is represented in XML schema by using the minOccurs and maxOccurs attributes on the element declaration.

For example:
<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>
denotes an 8-byte string that is optional, that is, it can occur zero or one times in the SOAP message.
The following example denotes a 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:
  • The minOccurs attribute specifies the minimum number of times the element can occur. It can have a value of 0 or any positive integer.
  • The maxOccurs attribute specifies the maximum number of time 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 there is no upper limit to the number of times the element can occur.
The default value for both attributes is 1.

In general, SOAP messages 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 receives a SOAP message, it is responsible for populating these structures and the application is responsible for reading them. Where CICS is sending a SOAP message, the application is responsible for populating these structures and CICS is responsible for reading them.

The format of these data structures is best explained with a series of examples. 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

Single, optional element

Start of changeThe second example illustrates an optional element that, if it occurs, occurs once.
<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>
In this case, the main data structure does not contain a declaration of an array. Instead, it contains a declaration of two fields:
05 component-num PIC S9(9) COMP-4
05 component-cont PIC X(16)
At run time, the first field (component-num) contains the number of times (zero or one in this case) that the element appears in the SOAP message, and the second field (component-cont) contains the name of a container.End of change
Start of changeA second data structure contains the declaration of the element itself:
01 DFHWS-component
  02 component PIC X(8)
So, to process the data structure in your application program, you must examine the value of component-num. If it is zero, there is no component element in the message, 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.End of change

Varying number of elements

Start of changeThe third 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 data structures are exactly the same as for a single, optional element. The main data structure contains:
05 component-num PIC S9(9) COMP-4
05 component-cont PIC X(16)
The second data structure contains:
01 DFHWS-component
  02 component PIC X(8)
Processing of the main data structure is similar to that in the previous example: you must examine the value of component-num (although this time it will contain a value in the range 1-5) to find out how many times the element occurs. The element contents are located in the container named in component-cont. The difference is that, this time, the container holds an array of elements, where each element is mapped by the DFHWS-component data structure.End of change

Summary

The last two cases are very similar - in fact they are both examples of the same general model. The rules can be summarized:
  • Where a varying array cannot be represented in the main data structure, each element of the array is represented in a second data structure.
  • The main data structure contains the number of elements in the array, and the name of a container which holds the array of elements.
  • Each element in the array is mapped by the secondary data structure associated with the array.
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.

Nested variable arrays

Complex SOAP messages may contain nested arrays with optional elements or with varying numbers of elements at different levels. When this is the case, the structure described is extended beyond the two levels described in the previous examples.

This example illustrates an optional element (<component2>) nested in a mandatory element (<component1>) that 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>
Start of changeThe top level data structure is exactly the same as in the previous examples:
05 component1-num PIC S9(9) COMP-4
05 component1-cont PIC X(16)
But the second data structure contains:
01 DFHWS-component1
  02 component2-num PIC S9(9) COMP-4
  02 component2-cont PIC X(16)
And a third level structure contains:
01 DFHWS-component2
  02 component2 PIC X(8)
End of change

Start of changeThe number of occurrences of the outermost element (<component1>) is in component1-num.End of change

Start of changeThe container named in component1-cont contains an array with that number of instances of the second data structure (DFHWS-component1).End of change

Start of changeEach instance of component2-cont names a different container, each of which contains the data structure mapped by the third level structure (DFHWS-component2).End of change

To illustrate this, consider the fragment of XML that matches the example:
<component1><component2>string1</component2></component1>
<component1><component2>string2</component2></component1>
<component1></component1>
There are three instances of <component1>. The first two each contain an instance of <component2>; the third instance does not.
Start of changeIn the top level data structure, component1-num contains a value of 3. In the container named in component1-cont are three instances of DFHWS-component1:
  1. In the first, component2-num has a value of 1, and the container named in component2-cont holds string1.
  2. In the second, component2-num has a value of 1, and the container named in component2-cont holds string2.
  3. In the third, component2-num has a value of 0, and the contents of component2-cont is 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.
End of change