Planning a SOAP service requester 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 requester in a straightforward way. You will, in almost every situation, 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. The application is ideally structured for reuse of the business logic in a web service requester.
Figure 1. Application partitioned into communications and business logic
In CICS Transaction Server, the business logic issues an EXEC CICS LINK command to link to the communication logic; the communication logic interacts with a server.
You cannot use the existing EXEC CICS LINK command to invoke CICS web services support in this situation:
  • When you are using the CICS web services assistant to generate the mapping between SOAP messages and application data structures, you must use an EXEC CICS INVOKE SERVICE command, and pass the application's data structure to CICS web services support. Also, the data types used in the interface to the business logic must be supported by the CICS web services assistant.

    However, if the target WEBSERVICE that your application program invokes is provider mode, i.e. a value has been defined for the PROGRAM attribute, CICS automatically optimizes the request using the EXEC CICS LINK command.

  • When you are not using the CICS web services assistant, you must construct your own messages, and link to program DFHPIRT.
Either way, it follows that your business logic cannot invoke a web service directly unless you are prepared to change the program. For the web services assistant, this option is shown in Figure 2, but it is not advisable in either case.
Figure 2. Simple deployment of CICS application as a web service requester
In CICS Transaction Server, the business logic issues an EXEC CICS INVOKE SERVICE command to invoke CICS web service support; web service support interacts with a server.

Using a wrapper program

A better solution, which keeps the business logic almost unchanged, is to use a wrapper program. The wrapper, in this case, has two purposes:
  • It issues an EXEC CICS INVOKE SERVICE command, or an EXEC CICS LINK PROGRAM(DFHPIRT), on behalf of the business logic. The only change in the business logic is the name of the program to which it links.
  • It can, if necessary, provide any data manipulation that is required if your application uses a data structure which the CICS web services assistant cannot map directly into a SOAP message.
For the case when the web services assistant is used, this structure is illustrated in Figure 3.
Figure 3. Deployment of CICS application as a web service requester using a wrapper program
In CICS Transaction Server, the business logic issues an EXEC CICS LINK command to a wrapper program; the wrapper issues an EXEC CICS INVOKE SERVICE command to invoke CICS web service support; web service support interacts with a server.

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. If your service requester application receives a SOAP fault message from the service provider, you need to decide how your application program should handle the fault message. CICS does not automatically roll back any changes when a SOAP fault message is received.

If you are planning to implement web service atomic transactions in your requester application program, the error handling is different. If the remote service provider encounters an error and rolls back its changes, a SOAP fault message is returned and the local transaction in CICS also rolls back. If local optimization is in effect, the service requester and provider use the same transaction. If the provider encounters an error, any changes made by the transaction in the requester are also rolled back.