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.
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 theminOccurs
attribute. It can also take a value ofunbounded
, which indicates that no upper limit applies to the number of times the element can occur. - The default value for both attributes is 1.
- Example: Denoting an 8-byte string that is optional
-
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>
- Example: Denoting an 8-byte string that must occur
-
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>
- 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
- Example: An element that occurs exactly three times
-
The following 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
- Example: a mandatory element that can occur from one to five times
-
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 fieldcomponent-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 incomponent-cont
; the container holds an array of elements, where each element is mapped by theDFHWS-component
data structure.
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.
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.
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.
- Example: Nested variable arrays
-
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 incomponent1-num
.The container named in
component1-cont
contains an array with that number of instances of the second data structureDFHWS-component1
.Each instance of
component2-cont
names a different container, each of which contains the data structure mapped by the third-level structureDFHWS-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 incomponent1-cont
has three instances ofDFHWS-component1
:- In the first,
component2-num
has a value of 1, and the container named incomponent2-cont
holds string1. - In the second,
component2-num
has a value of 1, and the container named incomponent2-cont
holds string2. - In the third,
component2-num
has a value of 0, and the contents ofcomponent2-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
- In the first,
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'.