Invoking a Web service from an application deployed with the Web services assistant

A service requester application that is deployed with the Web services assistant uses the EXEC CICS INVOKE WEBSERVICE command to invoke a Web service. The request and response are mapped to a data structure in container DFHWS-DATA.

  1. Create a channel and populate it with containers. At the minimum, container DFHWS-DATA must be present. It holds the top level data structure that CICS® will convert into a SOAP request. If the SOAP request contains any arrays that have varying numbers of elements, they are represented as a series of connected data structures in a series of containers. These containers must also be present in the channel.
  2. Invoke the target Web service. Use this command:

    EXEC CICS INVOKE WEBSERVICE(webservice)
                     CHANNEL(userchannel)
                     OPERATION(operation)

    where:
    • webservice is the name of the WEBSERVICE resource that defines the Web service to be invoked. The WEBSERVICE resource specifies the location of the Web service description, and the Web service binding file that CICS uses when it communicates with the Web service.
    • userchannel is the channel that holds container DFHWS-DATA and any other containers associated with the application's data structure.
    • operation is the name of the operation that is to be invoked in the target Web service.
    You can also specify URI(uri) where uri is the URI of the Web service to be invoked. If this option is omitted, then the Web service binding file associated with the WEBSERVICE resource definition must include either a provider URI (obtained from the Web service description by DFHWS2LS) or a provider application name (specified as a parameter to DFHWS2LS). If you specify this option, it is used in place of the URI or provider application name specified in the Web service binding file.
    The provider application name in the Web service binding file associated with the WEBSERVICE resource is used to enable local optimization of the Web service request. If you use this optimization, the EXEC CICS INVOKE WEBSERVICE command is optimized to an EXEC CICS LINK command. This optimization has an effect on the behavior of the EXEC CICS INVOKE WEBSERVICE command when the Web service is not expected to send a response:
    • When the optimization is not in effect, control returns from the EXEC CICS INVOKE WEBSERVICE command as soon as the request message is sent.
    • When the optimization is in effect, control returns from the EXEC CICS INVOKE WEBSERVICE command only when the target program terminates.
    When the Web service is expected to send a response, control returns from the command when the response is available.

    Start of changeYou can use this optimization only if the service provider application (as well as the service requester application) was deployed with the Web services assistant.End of change

  3. If the command was successful, retrieve the response containers from the channel. At the minimum, container DFHWS-DATA will be present. It holds the top level data structure that CICS created from the SOAP response. If the response contains any arrays that have varying numbers of elements, they are a represented as series of connected data structures in a series of containers. These containers will be present in the channel.
  4. Start of changeIf the service requester receives a SOAP fault message from the invoked Web service, you need to decide if the application program should roll back any changes. If this occurs, an INVREQ error with a RESP2 value of 6 is returned to the application program. However, if optimization is in effect, the same transaction is used in both the requester and provider. If an error occurs in a locally optimized Web service provider, all of the work done by the transaction rolls back in both the provider and the requester. An INVREQ error is returned to the requester with a RESP2 value of 16. End of change