Start of change

Support for XML attributes

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.
  1. An existence flag - this field is treated as a boolean data type and is typically one 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 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: 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)
End of change