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.
- 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.
<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>
<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>
- 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
<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
<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 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.
Varying number of elements at mapping level 2.1 and above
- 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.
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.
<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-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.
<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 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.
- 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'.