Customizing generated web service description documents

The web service description (WSDL) documents that are generated by DFHLS2WS contain some automatically generated content that might be appropriate for you to change before publishing. Customizing WSDL documents can result in regenerating the web services binding file and, in some cases, writing a wrapper program.

Follow these steps to customize generated web service description documents:

1. If you want to advertise support for HTTPS or communicate using IBM® MQ, use the URI parameter in DFHLS2WS to set an absolute URI. If you have not used the URI parameter, you must change the <wsdl:service> and <wsdl:binding> elements 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, use the URI parameter in DFHLS2WS to set an absolute URI. If you have not used the URI parameter, add the details to the soap:address in 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.
   You can make these changes without requiring any change to the web services binding file.

   If you are changing the port name and namespace without regenerating the WSBind file, the monitoring information might be wrong at runtime level 2.1 onwards.

3. Consider whether the automatically generated names in the WSDL document are appropriate for your purposes.
   You can rename these values:

   • 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 in the WSDL document.

   These values form part of the programmatic interface to which you code a client program. If the generated names are not sufficiently meaningful, maintenance of your application code might be more difficult over a long period of time. Use the DFHLS2WS REQUEST-NAMESPACE and RESPONSE-NAMESPACE parameters to change the targetNamespace of the XML schemas, and the WSDL-NAMESPACE parameter to change the targetNamespace of the WSDL document.

   If you change any of these values, you must use DFHWS2LS to regenerate the web services binding file. The language structures that are produced will not be the same as your existing language structures, 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 consider removing any fields that are not helpful to a web service client developer:

   • Fields that are used only for output values can be removed from the schema that maps the input data structures.
   • Filler fields.
   • Automatically generated annotations.
   If you make any of these changes, you must 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 must write a wrapper program to map data from the new representation to the old one. This wrapper program needs to perform an EXEC CICS LINK command 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.

5. If 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. When you override the mapping rules, ensure 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.