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:
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: A service requester must do the same in order to invoke the operation.

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.
Both utility programs generate a Web services binding file that CICS uses at run time to perform the mapping between the application program's data structures and the SOAP messages.

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>