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.
<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.<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: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.
<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
<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.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.<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.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.
<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>
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)
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).
<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.