The enterprise service tools capability in IBM® Rational® Developer for System z® is used to create service-oriented applications from enterprise artifacts. Single-service projects focus on the ability to create Web services that invoke a single transaction. Service flow projects help enable users to model a flow that aggregates multiple transactions in a single service.
The major Web services enablement scenarios typical for service-oriented architecture (SOA) are:
- "Bottom-up" development (enable existing enterprise applications as Web services)
- "Meet-in-the-middle" development (map to an existing service Interface)
- "Top-down development" (create a Web service implementation for a Web service)
Service flow projects offer the ability to aggregate multiple transactions into a single service, providing a powerful feature to developers that use this approach. But service flow projects always use a "bottom-up" approach to generate a Web service interface. Even if you use an existing service interface to describe the service interface of a flow, a service flow project will not generate that exact interface. This is because service flows run on the IBM CICS® service flow runtime, which requires certain metadata to invoke a service flow. Therefore, when a service flow project generates a Web service interface, the interface contains:
- Business data that is sent as input to the flow and received as output from the flow.
- Metadata that the CICS service flow runtime uses to invoke the flow.
For architectural or policy reasons it may not be possible to change an existing service interface. In that case a meet-in-the-middle (MIM) approach — that is, where an existing service interface (that does not contain service flow runtime metadata) is mapped to the service flow is necessary. Using a meet-in-the-middle approach you can create a Web service interface to a service flow.
Before attempting the methods described in this article, the developer should be familiar with IBM Rational Developer for System z, enterprise service tools, the CICS service flow feature, Web services concepts, and the COBOL language. To gain skills in these areas, please refer to the related resources section.
The projects in this article were developed and tested using IBM Rational Developer for System z version 7.6 on a Microsoft® Windows® XP Professional workstation. The screenshots you see in this article may reflect the particular settings of the environment in which the article was developed, which may differ from your own settings.
Overview and approach
In this article the "meet-in-the-middle" approach of Web service development will be used to map XML from an existing service interface definition to data structures in the generated COBOL output from a service flow project. This approach may be useful in any situation where a service flow is meant to be used with a service interface that cannot be changed, such as when a service flow that aggregates multiple existing terminal or non-terminal applications is required to process an XML document described by a schema that originates from a third party (such as a standards committee or another tool).
Because Web services generated by service flow projects require business data and service flow runtime metadata, a pre-existing service interface definition cannot automatically be used by a service flow project. This article will show you how to use service flow projects to generate a client requester program that invokes the service flow runtime with the necessary metadata, using business data passed in from a Web service. This step requires a small amount of COBOL coding. From there, you can use a Web Services for CICS project to complete the mapping from the existing interface definition and the client requester program. In the end, you will have a Web service implementation featuring an unmodified, existing service interface mapped to a service flow.
Download the sample Web service description and service flow project
In the Downloads section of this article, you will find an archive file (SFFMIM.zip) containing a generic Eclipse project with a Web Services Description Language (WSDL) file that describes a Web service that increments an input number (SFFMIM.wsdl) and a service flow project with a flow that implements the incrementing of an input number.
Start by downloading the SFFMIM.zip. Open the Enterprise Service Tools perspective in IBM Rational Developer for System z and import SFFMIM.zip as a project interchange file (File > Import > Project Interchange).
Figure 1. The service flow project SFFMIM after SFFMIM.zip is imported
Examine the sample Web service description
In the Navigator view, expand the GenericProject and open the file SFFMIM.wsdl. Note that the service describes an operation called IncrementOperation which uses the message IncrementRequest as an input and the message IncrementResponse as an output. The IncrementRequest message is comprised of a single integer element called requestNumber and the IncrementResponse message is comprised of a single integer element called the responseNumber.
Examine the sample service flow project
In the Flows folder of the SFFMIM project in the EST Project Explorer view, open the SFFMIM.seqflow file in the Flow Editor. The flow is trivial, containing only a receive node, an assign node, and a reply node. The interface to the flow has been created by importing SFFMIM.wsdl, and this is reflected by the input and output messages which correspond to the names of the receive node (IncrementOperationRequestMsg) and the reply node (IncrementOperationResponseMsg). Normally a flow is much more complex, containing multiple transaction invocation nodes and decision nodes. In this example the flow has been made as simple as possible so that you can concentrate on the MIM Web service enablement of the flow. For more information about modeling flows, refer to the related resources section.
Figure 2. SFFMIM.seqflow in the flow editor
Double-click on the assign node to open the mapping routine associated with it. Note that the mapping routine has a single mapping transform that sets the output message's responseNumber to the input message's requestNumber + 1. This flow increments the requestNumber and returns it as the responseNumber.
Figure 3. The assign node's mapping routine
Close the Mapping Editor and the Flow Editor. Expand the service flow project's Generation folder. Note that the flow has already been generated for CICS Service Flow Runtime Level 2.0. There is a generation properties file (SFFMIM_generation_props.sfgen), a generated COBOL program (SFFMIMP.cbl), and a service flow properties file (SFFMIMR.sfp). The COBOL program and service flow properties file are ready for deployment to CICS. Deployment involves compilation of the COBOL program, definition of CICS resources, placement of the service flow properties file in the service flow pickup directory, and scanning the service flow pickup directory. We will concentrate on developing the MIM Web service for this flow, and not on deployment steps. For more information about the deployment of service flows, refer to the related resources section.
Create a client requester program for the service flow
When a service flow is invoked, the program generated by the service flow project is not invoked directly. Instead the CICS service flow runtime interface program (DFHMADPL) is invoked, which takes business input data as well as service flow runtime-specific metadata as its input. DFHMADPL uses the metadata to invoke the generated COBOL program. For details about this process, refer to the related resources section.
Because the service flow runtime requires metadata and business data, it is necessary to implement an intermediate step between the Web service interface (which deals only with business data) and invocation of the runtime. This section describes the creation of a client requester program for the service flow. The client requester program will accept only business data as input and will invoke the service flow runtime with the necessary metadata statically defined. This eliminates the need for metadata to be included in a Web service interface definition, helping enable the existing service interface definition to be used to invoke the service flow.
To create the client requester program, follow these steps:
- Right-click on the generation properties file (SFFMIM_generation_props.sfgen), and select Generate > Client Requester. This action will launch a wizard that generates a COBOL program that invokes the Service Flow Runtime for the selected flow.
Figure 4. The generate client requester wizard
- Accept the default values and press Finish. This creates a COBOL program in the Generation folder called SFFMIMR.cbl and opens the new program in an editor.
Note: The wizard generates the client requester program based on customizable templates defined in the preferences (Window > Preferences > Enterprise Service Tools > Service Flow Projects > COBOL Requester Templates). You may find it useful to customize these templates.
- Examine the new COBOL program. It contains request and response data structures corresponding to the business data of the flow. It populates a Service Flow Runtime header with metadata about the flow that it is invoking. It invokes the DFHMADPL Service Flow Runtime interface program that will eventually invoke the generated service flow program, and it sets up some error handling logic after the flow invocation. Be careful here, as the generated program does not specify how the input data is populated and how the output data is returned. These steps must be coded.
- Modify SFFMIMR.cbl so that it reads input data and writes output data to the COMMAREA. First, insert the following data definition in the linkage section of the program:
05 INOUTDATA PIC S9(9) COMP-5 SYNC.
This defines the COMMAREA data structure, which will be used to link the input and output data between the client requester program and the outside world.
Now replace the line that says "*---->* code is required to get test input data from a source" with the following move statement:
MOVE DFHCOMMAREA TO CSFR-REQUEST.
This puts the data that has been sent in the COMMAREA into the data structure that is used for business input data.
Finally, in the section that checks for a normal return code, after the line that says "MOVE CSFR-DATA TO CSFR-RESPONSE", insert the following code:
MOVE CSFR-RESPONSE TO DFHCOMMAREA
This puts the business output data into the COMMAREA, where it can be read by an outside program.
In this section, you have created a client requester program for the flow called SFFMIMR. This program has a COMMAREA interface. It accepts the business input data of the service as input, populates the necessary service flow runtime metadata, invokes the sample service flow, and returns the business output data of the service as output. The client requester program is now ready for compilation and deployment on CICS. For your convenience, the source for the finished client requester program (SFFMIMR.cbl) is available in the Downloads section. Using this client requester program, you will now be able to complete the MIM development of a Web service for this service flow.
Develop a MIM Web service for the service flow
In this section you will create a single service project that will generate CICS Web service artifacts as well as a converter program that maps data between the XML Web service payload and COBOL input and output data structures in the client requester program that was generated in the previous section.
To enable the Web service, follow these steps:
- In the Enterprise Service Tools perspective, create a new Web Services for CICS Project (File > New > Web Services for CICS Project). On the first page of the wizard, choose a project name of SFFMIM_CICSWS, a development scenario of Map an Existing Service Interface (meet-in-middle), an application mode of Service Provider, and a conversion type of Compiled XML Conversion. Press Next.
Figure 5. New Web services for CICS project wizard
On the second page of the wizard, select the external interface definition file (SFFMIM.wsdl) and the client requester program (SFFMIMR.cbl) to be imported as source files. Press Finish.
Figure 6. New Web services for CICS project wizard, part two
- Select the new project, right-click and select Create mappings.
Figure 7. Launch create mappings wizard
On the first page of the wizard, select an operation type of Request-response. Press Next.
Figure 8. Create mappings wizard
On the second page of the wizard, select SFFMIM.wsdl as the XML source and SFFMIMR.cbl as the language target for the request to the Web service operation. Press Next.
Figure 9. Create mappings wizard - request
On the third page of the wizard, choose the message and the corresponding data structure for the request to the Web service operation. Choose IncrementRequest as the source XML element from the Web service definition and CSFR-REQUEST as the target language structure. Press Next.
Figure 10. Create mappings wizard – request, part two
On the fourth page of the wizard, accept the defaults and press Next.
Figure 11. Create mappings wizard – request, part three
On the fifth page of the wizard, select SFFMIMR.cbl as the language source and SFFMIM.wsdl as the XML target for the response to the Web service operation. Press Next.
Figure 12. Create mappings wizard – response
On the sixth page of the wizard, choose the data structure and corresponding message for the response to the Web service operation. Choose CSFR-RESPONSE as the source language structure and IncrementResponse as the target XML element from the Web service definition. Press Next.
Figure 13. Create mappings wizard – response, part two
On the seventh page of the wizard, accept the defaults and press Finish.
Figure 14. Create mappings wizard – response, part three
Files called request.mapping and response.mapping that contain the specified sources and targets will be created and opened in the Mapping Editor.
- Now you will define the request mapping. In request.mapping, drag the requestNumber element of the IncrementRequest source to the REQUESTNUMBER element of the CSFR-REQUEST target. This maps the XML request source to the COBOL data structure target. Save and close the file.
Figure 15. Defining the request mapping in the mapping editor
- Again, you will continue to define the response mapping. In Response.mapping, drag the RESPONSENUMBER element of the CSFR-RESPONSE source to the responseNumber element of the IncrementResponse target. This maps the COBOL data structure source to the XML response target. Save and close the file.
Figure 16. Defining the response mapping in the mapping editor
- Now you are ready to generate the Web services resources and the COBOL converter program. Right-click on the SFFMIM_CICSWS project and select Generate Web Services for CICS resources. This will launch another wizard. On the first page of the wizard, verify that the request and response mapping files are correct and press Next.
Figure 17. Web services for CICS generation wizard
On the second page of the wizard, select SFFMIM as the converter program name prefix and SFFMIMR (the client requester) as the service program name. Press Next.
Figure 18. Web services for CICS generation wizard, part two
On the third page of the wizard, select SFFMIM as the WSBind file name and SFFMIM as the log file name. Verify that the program interface is COMMAREA, since you defined SFFMIMR to have a COMMAREA interface. Accept the default values for the remainder of the wizard by pressing Finish.
Figure 19. Web services for CICS generation wizard, part three
In the Targets folder, note that SFFMIM.wsbind and SFFMIMD.cbl as well as a log file have been generated. SFFMIM.wsbind is the CICS artifact associated with the CICS Web Service, and SFFMIMD.cbl is the COBOL converter program that maps data between the XML Web service payload and the COBOL data structures in the SFFMIMR program.
In this section, you have used a single-service project to enable a meet-in-the-middle Web service that invokes the sample service flow. The complete single-service project (SFFMIM_CICSWS.zip) is available in the Downloads section. By creating the project, creating mappings, and running the generation wizard, you have produced the artifacts that will enable the service flow to be accessed using an existing service interface definition. All that remains is to compile the COBOL converter program, deploy the SFFMIM.wsbind to a CICS pipeline, and define the various CICS resources. These deployment steps are not covered in this article. For more information about the deployment of Web services, refer to the related resources section.
Following the approach above, you can now successfullycomplete the Web service enablement of a service flow with an existing service interface definition using enterprise service tools in Rational Developer for System z. Since the existing "bottom-up" style generation of Web service artifacts in service flow projects includes some service flow runtime metadata, it is unsuitable for use with an existing service interface definition. Instead, you have created a client requester that invokes the flow and statically handles the service flow runtime function's metadata needs, using a meet-in-the-middle single-service project to generate Web service artifacts plus a program that maps between your Web service's XML payload and your client requester's language structures.
|Service Flow Project and interface definition||SFFMIM.zip||15KB|
|Client requester Program for Service Flow||SFFMIMR.zip||24KB|
|Web Services for CICS Project||SFFMIM_CICSWS.zip||2KB|
- Using Rational Developer for System z to create a CICS COBOL Web service provider
- IBM Education Assistant for IBM Rational Developer for System z
- IBM Rational Developer for System z Information Center
- CICS Service Flow Runtime
- CICS Transaction Server for z/OS
- Learn about other applications in the IBM Rational Software Delivery Platform, including collaboration tools for parallel development and geographically dispersed teams, plus specialized software for architecture management, asset management, change and release management, integrated requirements management, process and portfolio management, and quality management. You can find product manuals, installation guides, and other documentation in the IBM Rational Online Documentation Center.
- Visit the Rational software area on developerWorks for technical resources and best practices for Rational Software Delivery Platform products.
- Explore Rational computer-based, Web-based, and instructor-led online courses. Hone your skills and learn more about Rational tools with these courses, which range from introductory to advanced. The courses on this catalog are available for purchase through computer-based training or Web-based training. Additionally, some "Getting Started" courses are available free of charge.
- Subscribe to the IBM developerWorks newsletter, a weekly update on the best of developerWorks tutorials, articles, downloads, community activities, webcasts and events.
- Browse the technology bookstore for books on these and other technical topics.
Get products and technologies
- Download trial versions of IBM Rational software.
- Download these IBM product evaluation versions and get your hands on application development tools and middleware products from DB2®, Lotus®, Tivoli®, and WebSphere®.
- Participate in the Rational Developer for System z forum.
- Check out developerWorks blogs and get involved in the developerWorks community.