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.
- 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.
- 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.
You
can use this optimization only if the service provider application (as well
as the service requester application) was deployed with the Web services assistant.
- 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.
If 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. 