SOAP messages and the application data structure

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.

A service requester is connected to CICS Transaction Server. A data mapper component between the pipeline and the application program uses a web service description and a web service binding file to map the SOAP body to an application data structure. — 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.

CICS Transaction Server is connected to a service provider. A data mapper component between the pipeline and the application program uses a Webservice description and a web service binding file to map the SOAP body to an application data structure. — 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.