In many cases, the CICS® Web services assistant can generate
the code to transform the data between a high level data structure used in
an application program, and the contents of the <Body> element
of a SOAP message. In these cases, when you write your application program,
you do not need to parse or construct the SOAP body; CICS will do this for you.
In order to transform the data, CICS needs information, at run time, about
the application data structure, and about the format of the SOAP messages.
This information is held in two files:
- The Web service binding file
This file is generated by the CICS Web services
assistant from an application language data structure, using utility program
DFHLS2WS, or from a Web service description, using utility program DFHWS2LS. CICS uses
the binding file to generate the resources used by the Web service application,
and to perform the mapping between the application's data structure and the
SOAP messages.
- The Web service description
This may be an existing Web service description,
or it may be generated from an application language data structure, using
utility program DFHLS2WS. CICS uses the Web service description to perform full
validation of SOAP messages.
Figure 1 shows where these files
are used in a service provider.
Figure 1. Mapping
the SOAP body to the application data structure in a service provider
A message handler in the pipeline (typically, a CICS-supplied SOAP message
handler) removes the SOAP envelope from an inbound request, and passes the
SOAP body to the data mapper function. This uses the Web service binding file
to map the contents of the SOAP body to the application's data structure.
If full validation of the SOAP message is active, then the SOAP body is validated
against the Web service description. If there is an outbound response, the
process is reversed.
Figure 2 shows where these files
are used in a service requester.
Figure 2. Mapping
the SOAP body to the application data structure in a service requester
For an outbound request, the data mapper function constructs
a SOAP body from the application's data structure, using information from
the Web service binding file. A message handler in the pipeline (typically,
a CICS-supplied SOAP message handler) adds the SOAP envelope. If there is
an inbound response, the process is reversed. If full validation of the SOAP
message is active, then the inbound SOAP body is validated against the Web
service description.
In both cases, the execution environment that allows a particular CICS application
program to operate in a Web services setting is defined by three objects.
These are the pipeline, the Web service binding file, and the Web service
description. The three objects are defined to CICS as attributes of the WEBSERVICE resource
definition.
There are some situations in which, even though you are using SOAP messages,
you cannot use the transformation that the CICS Web services assistant generates:
- When the same data cannot be represented in the SOAP message and in the
high level language.
All the high level languages that CICS supports,
and XML Schema, support a variety of different data types. However, there
is not a one-to-one correspondence between the data types used in the high
level languages, and those used in XML Schema, and there are cases where data
can be represented in one, but not in the other. In this situations, you should
consider one of the following:
- Change your application data structure. This may not be feasible, as it
might entail changes to the application program itself.
- Construct a wrapper program, which transforms the application data into
a form that CICS can
then transform into a SOAP message body. If you do this, you can leave your
application program unchanged. In this case CICS Web service support interacts directly
with the wrapper program, and only indirectly with the application program.
- When your application program is in a language which is not supported
by the CICS Web
services assistant.
In this situation, you should consider one of the following:
- Construct a wrapper program that is written in one of the languages that
the CICS Web
services assistant does support (COBOL, PL/I, C or C++).
- Instead of using the CICS Web services assistant, write your own program
to perform the mapping between the SOAP messages and the application program's
data structure.