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:
  1. An existence flag; this field is treated as a Boolean data type and is typically 1 byte in length.
  2. 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 with which they are associated. 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 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.
Optional attributes that have default values are treated as required attributes.
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.
When CICS produces a SOAP message based on the contents of a COMMAREA or container, the attribute is transformed and included in the message. When an application uses the TRANSFORM DATATOXML command, CICS also transforms the attribute and includes it in the XML.

The nillable attribute

The nillable attribute is a special attribute that can appear on an xsd: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)