Support for XML attributes
XML schemas can specify attributes that are allowed or required in XML. The CICS assistant utilities DFHWS2LS and DFHSC2LS ignore XML attributes by default. To process XML attributes that are defined in the XML schema, the value of the MAPPING-LEVEL parameter must be 1.1 or higher.
Optional attributes
Attributes can be optional or required and can be associated with any element in a SOAP message or XML for an application. 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 1 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 typeNMTOKEN
.
For example, consider the following schema attribute definition:
<xsd:attribute name="age" type="xsd:short" use="optional" />
This optional attribute maps 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
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.
When CICS transforms the data to XML, the following
runtime processing takes place:
- If the existence flag is set, the attribute is transformed and included in the XML.
- If the existence flag is not set, the attribute is not included in the XML.
Required attributes and runtime processing
For every attribute that is required, only the value field is generated in the appropriate language structure.If the attribute is present
in the XML, the value is mapped. If the attribute is not present,
the following processing occurs:
- If the application is a Web service provider, CICS generates a SOAP fault message indicating an error in the client SOAP message.
- If the application is a Web service requester, CICS issues a message and returns a conversion error response with a RESP2 code of 13 to the application.
- If the application is using the TRANSFORM XMLTODATA command, CICS issues a message and returns an invalid request response with a RESP2 code of 3 to the application.
The nillable attribute
The nillable attribute is a special attribute that can appear on anxsd:element
in an XML schema. It specifies that the xsi:nil
attribute is valid for the element in XML. 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, it is mapped as a required attribute that takes a Boolean value.
When CICS receives a SOAP message or has to transform XML for
an application that contains an xsi:nil
attribute,
the value of the attribute is true or false. If the value is true,
the application must ignore the values of the element or nested elements
in the scope of the xsi:nil
attribute.
When
CICS produces a SOAP message or XML based on the contents of a COMMAREA
or container for which the value for the
xsi:nil
attribute
is true, the following processing occurs:- The
xsi:nil
attribute is generated into the XML or SOAP message. - The value of the associated element is ignored.
- Any nested elements within the element are ignored.
SOAP message example
Consider the following example XML schema, which could be part of a WSDL document:<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>
Here is an example of a partial SOAP message that conforms
to this schema:<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 maps to these elements: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)