Running the Web services assistant program DFHLS2WS

The CICS® Web services assistant consists of two batch programs which can help you to transform existing CICS applications into Web services, and to enable CICS applications to use Web services provided by external providers. Program DFHLS2WS transforms a language structure to generate a Web service binding file and a Web service description.

  1. Copy the supplied sample JCL to a suitable working file. The JCL is supplied in samples/webservices/JCL/LS2WS.
  2. Add a valid JOB card to the JCL.
  3. Code the parameters for DFHLS2WS. The required parameters for the INQUIRE SINGLE ITEM function of the example application are:
    //INPUT.SYSUT1 DD *                     
    LOGFILE=/u/exampleapp/wsbind/inquireSingle.log      
    PDSLIB=CICSHLQ.SDFHSAMP                 
    REQMEM=DFH0XCP4
    RESPMEM=DFH0XCP4                        
    LANG=COBOL 
    PGMNAME=DFH0XCMN                        
    PGMINT=COMMAREA                         
    URI=exampleApp/inquireSingle
    WSBIND=/u/exampleapp/wsbind/inquireSingle.wsbind    
    WSDL=/u/exampleapp/wsdl/inquireSingle.wsdl          
    */                                      
    The parameters are as follows:
    LOGFILE=/u/exampleapp/wsbind/inquireSingle.log
    The file that is used to record diagnostic information from DFHLS2WS. The file is normally used only by IBM's software support organization.
    PDSLIB=CICSHLQ.SDFHSAMP
    The name of the partitioned data set (PDS) where the Web service assistant will look for copybooks that define the request and response structures. In the example this is SDFHSAMP of the CICS installed datasets.
    REQMEM=DFH0XCP4
    RESPMEM=DFH0XCP4
    These parameters define the language structure for the request and the response to the program. In the example the request and the response have the same structure and are defined by the same copybook.
    LANG=COBOL
    The target program and the data structures are written in COBOL
    PGMNAME=DFH0XCMN
    The name of the target program that will be invoked when a Web service request is received.
    PGMINT=COMMAREA
    The target program is invoked with a COMMAREA interface.
    URI=exampleApp/inquireSingle
    The unique part of the URI that will be used in the generated Web service definition, and used to create the URIMAP resource that will map incoming requests to the correct Web service. The value specified will result in the service being available to external clients at: 
    http://mycicsserver:myport/exampleApp/inquireSingle
    where mycicsserver and myport are the CICS server address and the port onto which this WEBSERVICE has been installed.
    Note: The parameter does not have a leading '/'.
    WSBIND=/u/exampleapp/wsbind/inquireSingle.wsbind
    The location on HFS to which the Web service binding file will be written.
    Note: If the file is to be used with the PIPELINE scanning mechanism it must have the extension .wsbind.
    WSDL=/u/exampleapp/wsdl/inquireSingle.wsdl
    The location on HFS to which the file containing the generated Web service description will be written. It is good practice to use matching names for the Web service binding file and its corresponding Web service description.
    Tip: Conventionally, files containing Web service descriptions have the extension .wsdl.
    The Web services description provides the information that a client needs to access the Web service. It contains an XML schema definition of the request and response, and location information for the service.
  4. Run the job. A Web service description and Web service binding file will be created in the locations specified.
  5. Customize the service location in the Web service description. As generated, the <service> element contains the following:
    <service name="DFHCMNService">
    <port binding="tns:DFH0XCMNHTTPSoapBinding" name="DFH0XCMNPort">
    <soap:address location="http://my-server:my-port/exampleApp/inquireSingle"/>
    </port>
    </service> 
    Before the Web service description can be published to clients, you must make the following changes:
    1. Replace my-server with the CICS server location.
    2. Replace my-port with the port number.