XML schemas can specify attributes that are allowed or required
in a SOAP message. The Web services assistant utility DFHWS2LS ignores XML
attributes by default. To process XML attributes that are defined in the XML
Schema, apply APAR PK15904 and then change the value of the MAPPING-LEVEL parameter
to 1.1 or higher in DFHWS2LS.
Optional attributes
Attributes can be optional or required
and can be associated with any element in the SOAP message. For every optional
attribute defined in the schema, two fields are generated in the appropriate
language structure.
- An existence flag - this field is treated as a boolean data type and is
typically one byte in length.
- A value - this field is mapped in the same way as an equivalently typed
XML element. For example, an attribute of type NMTOKEN is
mapped in the same way as an XML element of type NMTOKEN.
The attribute existence and value fields appear in the generated language
structure before the field for the element they are associated with. Unexpected
attributes that appear in the instance document are ignored.
For example, consider the following schema attribute definition:
<xsd:attribute name="age" type="xsd:short" use="optional" />
This optional attribute would be mapped to the following COBOL structure:
05 attr-age-exist PIC X DISPLAY
05 attr-age-value PIC S9999 COMP-5 SYNC
Runtime processing of optional attributes
When CICS
receives and reads SOAP messages, the following runtime processing takes place
for optional attributes:
- If the attribute is present, the existence flag is set and the value is
mapped.
- If the attribute is not present, the existence flag is not set.
- If the attribute has a default value and is present, the value is mapped.
- If the attribute has a default value and is not present, the default value
is mapped.
Optional attributes that have default values are treated as required
attributes.
When CICS produces a SOAP message based on the contents of
a COMMAREA or a container, the following runtime processing takes place:
- If the existence flag is set, the attribute is transformed and included
in the message.
- If the existence flag is not set, the attribute is not included in the
message.
Required attributes and runtime processing
For every
attribute that is required, only the value field is generated in the appropriate
language structure.
When CICS receives and reads SOAP messages at run time,
if the attribute is present then the value is mapped. If the attribute is
not present:
- As the provider, CICS generates a SOAP fault message indicating there
is an error in the client's SOAP message.
- As the requester, CICS returns a conversion error resp2 code of 13 to
the application.
When CICS produces a SOAP message based on the contents of a COMMAREA
or container, the attribute is transformed and included in the message.
The nillable attribute
The nillable attribute is a
special attribute that can appear on an
xsd:element within
an XML schema. It specifies that the
xsi:nil attribute is
valid for the element in a SOAP message. If an element has the
xsi:nil attribute
specified, it indicates that the element is present but has no value, and
therefore no content is associated with it.
If an XML schema has defined
the nillable attribute as true, then it is mapped as a required attribute
that takes a boolean value.
In runtime processing, when CICS receives
a SOAP message and reads an
xsi:nil attribute:
- The value of the attribute is true or false.
- If the value is true, the values of the element or nested elements within
the scope of the xsi:nil attribute must be ignored by the
application.
When CICS produces a SOAP message based on the contents of a COMMAREA
or container for which the value for the
xsi:nil attribute
is true:
- The xsi:nil attribute is generated into the SOAP message.
- The value of the associated element is ignored.
- Any nested elements within the element are ignored.
Consider the following example XML schema, which could be part of
a WSDL document:
<?xml version="1.0"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<xsd:element name="root" nillable=”true”>
<xsd:complexType>
<xsd:sequence>
<xsd:element nillable="true" name="num" type="xsd:int" maxOccurs=”3” minOccurs=”3”/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>
An example of a partial SOAP message that conforms
to this schema is:
<?xml version="1.0"?>
<root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<num xsi:nil="true"/>
<num>15</num>
<num xsi:nil=”true”/>
</root>
In COBOL, this SOAP message would map to:
05 root
10 attr-nil-root-value PIC X DISPLAY
10 num OCCURS 3
15 num1 PIC S9(9) COMP-5 SYNC
15 attr-nil-num-value PIC X DISPLAY
10 filler PIC X(3)