Planning a service provider application

In general, CICS® applications should be structured to ensure separation of business logic and communications logic. Following this practice will help you to deploy new and existing applications in a Web service provider in a straightforward way. You will, in some situations, need to interpose a simple wrapper program between your application program and CICS Web service support.

Figure 1 shows a typical application which is partitioned to ensure a separation between communication logic and business logic.
Figure 1. Application partitioned into communications and business logicA client interacts with communications logic in CICS Transaction Server, the communications logic issues an EXEC CICS LINK command to link to the business logic.
In many cases, you can deploy the business logic directly as a service provider application. This is illustrated in Figure 2.
Figure 2. Simple deployment of CICS application as a Web service providerA client interacts with Web service support in CICS Transaction Server; Web service support links to the business logic.
To use this simple model, the following conditions apply:
When you are using the CICS Web services assistant to generate the mapping between SOAP messages and application data structures:
The data types used in the interface to the business logic must be supported by the CICS Web services assistant. If this is not the case, you must interpose a wrapper program between CICS Web service support and your business logic.

You will also need a wrapper program when you deploy an existing program to provide a service that conforms to an existing Web service description: if you process the Web service description using the assistant, the resulting data structures are very unlikely to match the interface to your business logic.

When you are not using the CICS Web services assistant:
Message handlers in your service provider pipeline must interact directly with your business logic.

Using a wrapper program

Use a wrapper program when the CICS Web services assistant cannot generate code to interact directly with the business logic. For example, the interface to the business logic might use a data structure which the CICS Web services assistant cannot map directly into a SOAP message. In this situation, you can use a wrapper program to provide any additional data manipulation that is required:
Figure 3. Deployment of CICS application as a Web service provider using a wrapper programA client interacts with Web service support in CICS Transaction Server; Web service support links to a wrapper program; the wrapper program issues an EXEC CICS LINK command to link to the business logic.
You will need to design a second data structure that the assistant can support, and use this as the interface to your wrapper program. The wrapper program then has two simple functions to perform:
Start of change

Error handling

If you are planning to use the CICS Web services assistant, you should also consider how to handle rolling back changes when errors occur. When a SOAP request message is received from a service requester, the SOAP message is transformed by CICS just before it is passed to your application program. If an error occurs during this transformation, CICS does not automatically roll back any work that has been performed on the message. For example, if you plan to add some additional processing on the SOAP message using handlers in the pipeline, you need to decide if they should roll back any recoverable changes that they have already performed.

On outbound SOAP messages, for example when your service provider application program is sending a response message to a service requester, if CICS encounters an error when generating the response SOAP message, all of the recoverable changes made by the application program are automatically backed out. You should consider whether adding synchronization points is appropriate for your application program.

If you are planning to use Web service atomic transactions in your provider application, and the Web service requester also supports atomic transactions, any error that causes CICS to roll back a transaction would also cause the remote requester to roll back its changes.

End of change