WSDL and the application data structure
A web service description contains abstract representations of the input and output messages used by the service. CICS® uses the web service description to construct the data structures used by application programs. At run time, CICS performs the mapping between the application data structures and the messages.
The description of a web service contains, among other things:
- One or more operations
- For each operation, an input message and an optional output message
- For each message, the message structure, defined in terms of XML data types. Complex data types used in the messages are defined in an XML schema which is contained in the <types> element within the web service description. Simple messages can be described without using the <types> element.
WSDL contains an abstract definition of an operation, and the associated
messages; it cannot be used directly in an application program. To
implement the operation, a service provider must do the following:
- It must parse the WSDL, in order to understand the structure of the messages
- It must parse each input message, and construct the output message
- It must perform the mappings between the contents of the input and output messages, and the data structures used in the application program
When you use the the CICS web services assistant, much of this is done for you, and you can write your application program without detailed understanding of WSDL, or of the way the input and output messages are constructed.
The CICS web services assistant consists of two
utility programs:
- DFHWS2LS
- This utility program takes a web service description as a starting point. It uses the descriptions of the messages, and the data types used in those messages, to construct high-level language data structures that you can use in your application programs.
- DFHLS2WS
- This utility program takes a high-level language data structure as a starting point. It uses the structure to construct a web services description that contains descriptions of messages, and the data types used in those messages derived from the language structure.
An example of COBOL to WSDL mapping
This example shows how the data structure used in a COBOL program is represented in the web services description that is generated by the CICS web services assistant.Figure 1 shows
a simple COBOL data structure:
Figure 1. COBOL
record definition of an input message defined in WSDL
* Catalogue COMMAREA structure
03 CA-REQUEST-ID PIC X(6).
03 CA-RETURN-CODE PIC 9(2).
03 CA-RESPONSE-MESSAGE PIC X(79).
* Fields used in Place Order
03 CA-ORDER-REQUEST.
05 CA-USERID PIC X(8).
05 CA-CHARGE-DEPT PIC X(8).
05 CA-ITEM-REF-NUMBER PIC 9(4).
05 CA-QUANTITY-REQ PIC 9(3).
05 FILLER PIC X(888).
The key elements in the corresponding fragment of the
web services description are shown in Figure 2:
Figure 2. WSDL fragment
derived from a COBOL data structure
<xsd:sequence>
<xsd:element name="CA-REQUEST-ID" nillable="false">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:length value="6"/>
<xsd:whiteSpace value="preserve"/>
</xsd:restriction>
</xsd:simpleType>
</xsd:element>
<xsd:element name="CA-RETURN-CODE" nillable="false">
<xsd:simpleType>
<xsd:restriction base="xsd:short">
<xsd:maxInclusive value="99"/>
<xsd:minInclusive value="0"/>
</xsd:restriction>
</xsd:simpleType>
</xsd:element>
<xsd:element name="CA-RESPONSE-MESSAGE" nillable="false">
...
</xsd:element>
<xsd:element name="CA-ORDER-REQUEST" nillable="false">
<xsd:complexType mixed="false">
<xsd:sequence>
<xsd:element name="CA-USERID" nillable="false">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:length value="8"/>
<xsd:whiteSpace value="preserve"/>
</xsd:restriction>
</xsd:simpleType>
</xsd:element>
<xsd:element name="CA-CHARGE-DEPT" nillable="false">
...
</xsd:element>
<xsd:element name="CA-ITEM-REF-NUMBER" nillable="false">
...
</xsd:element>
<xsd:element name="CA-QUANTITY-REQ" nillable="false">
...
</xsd:element>
<xsd:element name="FILLER" nillable="false">
...
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>