Start of change

Customizing generated Web service description documents

The Web service description (WSDL) documents that are generated by DFHLS2WS contain some automatically generated content that it might be appropriate for you to change before publishing. For example, the WSDL generated by DFHLS2WS assumes the use of SOAP version 1.1 over HTTP.

Customizing WSDL documents can result in regenerating the Web services binding file and in some cases, writing a wrapper program.
  1. If you want to advertise support for SOAP 1.2, HTTPS or communicate using WebSphere MQ, then you need to change the wsdl:service and wsdl:binding tags at the end of the WSDL document. The generated WSDL includes comments to assist you in making these changes. Changing these elements does not require you to regenerate the Web services binding file.
  2. If you want to supply the network location of your Web service, add the details to the soap:address within the wsdl:service element.
    1. If you are using an HTTP-based protocol, replace my-server with the TCP/IP host name of your CICS region and my-port with the port number of the TCPIPSERVICE resource.
    2. If you are using WebSphere MQ as the transport protocol, replace myQueue with the name of the appropriate queue.
    These changes can be made without requiring any change to the Web services binding file.
  3. Consider if the automatically generated names in the WSDL document are appropriate for your purposes. The values that you can rename are:
    • The targetNamespace of the WSDL document
    • The targetNamespace of the XML schemas within the WSDL document
    • The wsdl:portType name
    • The wsdl:operation name
    • The wsdl:binding name
    • The wsdl:service name
    • The names of the fields in the XML schemas within the WSDL document.
    These values form part of the programmatic interface to which a client program must be coded. If the generated names are not sufficiently meaningful, it could make maintenance of your application code harder over a long period of time. Start of changeIt is recommended that you use the DFHLS2WS parameters REQUEST-NAMESPACE and RESPONSE-NAMESPACE to change the targetNamespace of the XML schemas.End of change

    If you change any of these values, you need to regenerate the Web services binding file using DFHWS2LS. The language structures that are produced will not be the same as your existing language structure, but are compatible with your existing application, so no application changes are required. However, you can ignore the new language structures and use the new Web services binding file with the original structures.

  4. Consider if the COMMAREA fields exposed in the XML schemas are appropriate. You might want to consider removing those fields that are not helpful to a Web service client developer. For example:
    • fields that are only used for output values could be removed from the schema that maps the input data structures
    • filler fields
    • automatically generated annotations
    If you make any of these changes, you need to regenerate the Web services binding file using DFHWS2LS. The new language structures that are generated are not compatible with the original language structures, so you need to write a wrapper program to map data from the new representation to the old one. This wrapper program needs to LINK to the target application program and then map the returned data.

    This level of customization requires the most effort, but results in the most meaningful programmatic interfaces for your Web services client developers to work with.

  5. Start of changeIf you want to put the generated WSDL document through DFHWS2LS to create new language structures, decide whether to keep the annotations in the WSDL document. The annotations override the normal mapping rules when DFHWS2LS generates the language structures. Overriding the mapping rules ensures that the generated language structures are compatible with the version that was used by DFHLS2WS. If you want to use the default mapping rules to produce the language structures, remove the annotations.End of change
For an example of a WSDL document, see An example of the generated WSDL document.
End of change