 | Level: Intermediate Wilbert Kho (wilbert@us.ibm.com), Consulting Certified Software IT Specialist, IBM
23 Nov 2005 CICS® Transaction Server for z/OS® V3.1 provides comprehensive supportfor Web services, enabling CICS applications to act as either service providers or service requesters. WebSphere® Developer for zSeries V6 automates the transformation of existing CICS COBOL applications so that these can act as service providers.
Introduction
This article shows how to transform an existing CICS COBOL application so that it can be accessed as a Web service through the CICS Web services facilities of CICS Transaction Server for z/OS V3.1 (hereafter referred to as CICS TS), using the XML Services for the Enterprise (XSE) component of WebSphere Developer for zSeries V6.0 (hereafter referred to as WebSphere Developer). This article extends the information previously discussed in the
article Developing a CICS-based Web service with WebSphere Studio Enterprise Developer and SOAP for CICS, and applies its usage to the Web services facilities of CICS TS V3.1.
The article will guide you through generating:
- A driver/converter program and WSBind file that can be deployed to a CICS Transaction Server for z/OS V3.1 system
- WSDL (Web Services Description Language) and XSD (XML Schema Definition) files that describe the CICS-based service.
It also describes the steps needed to build and deploy the necessary artifacts to the CICS Transaction Server for z/OS
system, and shows you ways to test the CICS-based service.
Before starting, you need WebSphere Developer for zSeries V6. You also need access to a CICS Transaction Server for a z/OS V3.1 system.
The examples in this article were developed using a z/OS V1R6 system called DEMOMVS that is running CICS Transaction Server for z/OS V3R1. In addition, the z/OS components of WebSphere Developer were installed and enabled.
The wdzcws.zip file provided as a download
with this article provides the artifacts that you need to work through this article. Unzip the file in the \wdzcws\artifacts
subdirectory, which I will refer to as the artifacts directory.
WebSphere Developer for zSeries overview
WebSphere Developer for zSeries V6 is based on the IBM Rational Software Development Platform and facilitates the development of both Java- and z/OS-based applications. It includes capabilities that make traditional z/OS mainframe development, Web development, and integrated composite development faster and more efficient. It reduces the complexity and effort required to create mixed workload applications by supporting and leveraging the heterogeneous skill sets (COBOL, PL/I, and Java) in IT organizations. In particular, WebSphere Developer contains tools that support the development of Web services and the XML enablement of existing z/OS COBOL applications. This makes it easier to create the distributed and z/OS-based components that form parts of a Service Oriented Architecture (SOA).
The XML Services for the Enterprise (XSE) capability of WebSphere Developer provides tools that let you easily adapt COBOL-based applications so that they can consume and produce XML messages. This adaptation is accomplished without modifying the existing COBOL applications; and, more importantly, without modifying other applications that call the existing COBOL application. A COBOL application must be able to processing XML messages to become a Web service, since XML is the language used to describe the Web service request and the parameters that are passed to the existing application. XSE supports the creation of driver programs that work with existing CICS or IMS applications.
An important task in this enablement is the mapping of XML elements to COBOL data items, which can be accomplished with the following three approaches:
- Bottom-up -- Start from an existing COBOL application or copybook that contains the interface definitions, i.e., with COBOL at the
bottom, derive the XML data model from it, and generate the mapping or conversion code.
- Meet-in-the-middle-- Given an existing COBOL interface definition (as defined above) and a XML description (XML schema, DTD, WSDL), create a mapping definition file that connects COBOL data items to XML elements. Derive the XML data model based on the specified mapping, and generate the mapping/conversion code.
- Top-down -- Start from an existing XML description of the interface (XML schema, DTD, WSDL), derive the XML data model, and generate the mapping/conversion code.
The first two approaches essentially transform existing COBOL applications and make them available as service providers. The third approach assists in the creation of a COBOL-based service requester, which is essentially dealing with a new application. WebSphere Developer for zSeries V6 currently supports the bottom-up and meet-in-the-middle approaches. In the context of running in the Web services environment of CICS TS V3.1, this article will focus solely on the bottom-up approach.
The Web Services Enablement wizard is the XSE tool that supports the bottom-up approach. It takes as input COBOL data declarations that define the input and output interfaces for a COBOL application. The XML structure and data types are derived from the COBOL data declarations. Based on these, the Web Services Enablement wizard generates the following set of artifacts (see Figure 1):
Figure 1. Generated
artifacts
- Input converter -- COBOL program that takes an incoming XML document and maps it into the
corresponding COBOL data structure that the existing COBOL application expects.
- Output converter -- COBOL program that takes the COBOL data results returned from the
existing COBOL application and maps them to an XML document.
- Converter driver -- COBOL program that shows how the input and output converters can be
used to interact with the existing COBOL application. You can generate four different types of converter drivers:
- Batch,TSO and USS
- IMS SOAP Gateway
- SOAP for CICS
- Web Services for CICS
This article looks at the Web Services for CICS converter type (see Figure 2).
Figure 2. Converter Types
- Input document XML schema definition (XSD)-- XML schema that describes the incoming XML document for processing by the input converter
- Output document XML schema definition(XSD)-- XML schema that describes the outgoing XML document produced by the output converter
- Web Services Description Language (WSDL)-- XML-based language for describing Web services and how to access them. It also contains the XML schemas. Previously with WebSphere Studio Enterprise Developer, parts of the WSDL had to be manually created.
- WSBind-- Web service binding file used by CICS Transaction Server for z/OS V3.1 to perform the mapping between application data structures and XML-based SOAP messages. This file is generated when you choose the
Web Services for CICS converter type This feature is new with WebSphere Developer, as part of its support for CICS TS V3.1.
 |
CICS Web Services
Support for Web services in CICS Transaction Server for z/OS V2.2 and V2.3 was provided through the SOAP for CICS feature. This support has now been fully integrated into CICS Transaction Server for z/OS V3.1. In this release, CICS applications can act in the role of both service provider and service requester, where the services are defined using Web Services Description Language (WSDL). The infrastructure provided as part of CICS TS V3.1 includes a distributed
transaction coordination capability compatible with the WS-AtomicTransaction specification.
The CICS TS V3.1 support for Web services includes the CICS Web
services assistant, a batch utility which can help you to:
- Transform an existing CICS application into a Web service.
- Enable a CICS application to use a Web service provided by an external provider.
The assistant can create a WSDL document from a simple language structure, or a language structure from an existing WSDL document, and supports COBOL, C/C++, and PL/I. It also generates information used to enable automatic runtime conversion of SOAP messages to containers and COMMAREAs, and vice versa.
The XSE capability of WebSphere Developer extends and complements this by converting COBOL types and constructs that are not covered natively by the CICS Web services assistant. For example, OCCURS DEPENDING ON and REDEFINES on data description entries are not supported by the assistant. WebSphere Developer also has Web services tools for testing the CICS-based Web service from the generated WSDL, and tools that can facilitate the creation of Java-based clients.
Overview of development tasks
To create a CICS Web service, you need to perform the following development tasks, which I'll cover in detail in the following sections:
- Import the COBOL interface definition into a z/OS Local Project
- Use the Web Services Enablement wizard to generate the converter
driver, input and output converters, XML schemas, WSDL, and WSBind files
- Build and deploy the generated artifacts to CICS TS
- Use the Web Services Explorer tool to test the CICS-based Web service
This article was developed and tested on a Windows XP workstation connected to a z/OS system called DEMOMVS. This article assumes you have started WebSphere Developer and are familiar with the use of its major components. Parts of the article require that you have established connectivity to a z/OS system that contains a running CICS
TS V3.1 region.
Task 1. Import the COBOL interface definition into a z/OS Local Project
In this first task, you import an existing CICS COBOL application into a z/OS local project. The Web Services Enablement tool of WebSphere Developer can work with either a complete COBOL source program or a COBOL copybook that contains the data declarations describing the interface to the application. The CICS COBOL source program is WBCSCUST. Given a customer number, WBCSCUST will return information about that customer. The source for this is WBCSCUST.cbl
in the artifacts directory. Listing 1 shows the interface to WBCSCUST:
Listing 1. Interface to WBCSCUST (DFHCOMMAREA)
01 DFHCOMMAREA.
02 CustNo PIC S9(9) COMP-5.
02 LastName PIC A(25).
02 FirstName PIC A(15).
02 Address1 PIC X(20).
02 City PIC A(20).
02 State PIC A(5).
02 Country PIC X(15).
02 RetCode PIC S9. |
Create a z/OS Local Project using the New creation wizard (see Figure 3) and import WBCSCUST.cbl. from the artifacts directory into this project. Use cicsws as the name of the project.
Figure 3. Create
a z/OS Local Project
An alternative to using the import facility is to use the Remote Systems view (see Figure 4) to navigate to the artifact directory to copy and paste the file to the z/OS Local Project.
Figure 4. Remote Systems view
Task 2. Generate converter program, XML schemas, WSDL, and WSBind
Next, use the Generate enablement components wizard to generate the COBOL programs that make up the CICS Web services conversion program for WBCSCUST. You also generate the XML schemas that describe the input and output XML messages, the WSDL file that describes the CICS-based service, and the WSBind file that is used by CICS TS V3.1 to determine how conversion is to be done.
- Right-click WBCSCUST.cbl from the cicsws local project, and select Enable Web Service => Generate enablement components to launch the Web Services Enablement wizard.
- On the Enable Web Service Wizard - Data Structures page, make sure the Inbound data structure tab is
selected. Expand DFHCOMMAREA by clicking the + sign beside it and select CustNo as the only element that will form the data structure for the inbound XMLconverter, as shown in Figure 5.
Figure 5. Selecting the Inbound data structure
- Select the Outbound data structure tab. Click the DFHCOMMAREA checkbox to
select all the data items as part of the data structure for the outbound XMLconverter (see Figure 6).
Figure 6. Selecting the Outbound data structure
Click Next> to continue.
- On the Enable Web Service Wizard - Generation Options page, make sure the XML Converter Options tab is selected. Select Web Services for CICS as the converter type and specify WBCSCU
as the program name prefix.
Figure 7. Converter options.
Suffixes will be added to the program name prefix to form the program-ids of the driver and converter programs. For example, with a program name prefix of WBCSCU, the program-id of the driver program will be WBCSCUD. CICS will look into the WSBind file for the name of the conversion program to be invoked. WebSphere Developer will store the program-id of the driver program in the WSBind file; therefore, the conversion program (driver/converters) must be built into a load module with the name WBCSCUD.
- Select the WSDL and XSD Options tab. Specify the following as the endpoint URI, as shown in Figure 8:
http://demomvs.demopkg.ibm.com:3091/wdz/CustInquiry
This will be the SOAP address that is used to reach the target CICS system where the conversion program (WBCSCUD) is deployed. The transport used is HTTP. The local URI portion (/wdz/CustInquiry) will be used to create the URIMAP on CICS for matching URI requests. The hostname (demomvs.demopkg.ibm.com) specified is that of the DEMOMVS system and the port number used for CICS Web Services on the DEMOMVS system is 3091. Substitute the hostname and the port number with the appropriate values for your system.
Figure 8. Specifying the endpoint
Click Next> to continue.
- On the Web Service Wizard - Web Services for CICS page, make sure the WSBind Properties tab is selected. Accept the default WSBind file name of WBCSCUST. Select DFHCOMMAREA as the program interface, as shown in Figure 9.
Figure 9. WSBind
The program interface can be either DFHCOMMAREA or the new CONTAINER support in CICS 3.1. Since we are transforming an existing CICS COBOL application, this will be using the DFHCOMMAREA interface. The WSBind file will be created with a file extension of wsbind, which is in binary EBCDIC format.
- Select the Advanced WSBind Properties tab. as shown in Figure 10. Review and accept the default values. Note that the Local URI was taken from part of the Endpoint URI that was specified earlier.
Figure 10. Advanced WSBind specifications
A PIPELINE is a CICS resource that is used when a CICS application is in the role of a Web service provider or requester. It provides information about the message handler programs that act on a service request and on the response. Typically, a single PIPELINE definition can be used by many applications. We will defer the specification of the PIPELINE until deployment.
You can ask CICS Web Services to validate the WSDL that is used by specifying the HFS path on the target z/OS system where the WSDL file is located. This is usually done during testing or debugging and is not recommended for production.
Click Next> to continue.
- On the Enable Web Service Wizard - File, data set, or member selection page, make sure the XML Converters tab is selected. Specify a converter driver file name of WBCSCUD. Check the Generate all to driver box, as shown in Figure 11:
Figure 11. Conversion program file name
- Select the WSDL and XSD tab. Review and accept the default values (see Figure 12).
Figure 12. WSDL and XSD file names
Click Finish to complete the generation of the conversion program (converter driver, input and output converters),
WSBind, XSD, and WSDL files.
- After the Web Services Enablement wizard completes its generation, you should see five additional artifacts in the cicsws
z/OS Local Project (shown in Figure 13).
- WBCSCUD.cbl is the conversion program (converter driver, input and output converters).
- WBCSCUST.wsbind is the WSBind file that tells CICS how conversion is to be performed and what the URI map looks like.
- WBCSCUST.wsdl is the WSDL file that describes this CICS-based Web service.
- WBCSCUSTI.xsd and WBCSCUSTO.xsd are the XML Schema Definition files that describe the input and output XML documents respectively.
Figure 13. Generated artifacts
- Double-click on WBCSCUD.cbl to open it in the z/OS LPEX Editor. Use the z/OS LPEX Editor to explore the code to understand the productivity you gained from not having to develop the conversion program manually. Note that the converter driver for CICS Web Services is different from the driver for SOAP for CICS, specifically with its interaction with the existing program. The SOAP for CICS driver contains an EXEC CICS LINK to the existing program. The CICS Web Services driver has no call at all to the existing program. This is because the CICS Web Service is responsible for calling the existing program. Close the editor when you are done exploring.
|
Task 3. Build and deploy generated artifacts to CICS
The next task is to build and deploy the conversion program and WSBind file to z/OS.
- Move the conversion program to the target z/OS system by using the Remote System Explorer facilities of WebSphere Developer to copy the generated conversion program from the z/OS Local Project to a PDS or library.
- Compile and link-edit the conversion program to create the load module to be deployed to CICS. You can use the z/OS Application Development tools of WebSphere Developer to generate and submit the needed JCL.
- After you create the load module, make it available to CICS by copying to a PDS or library that is part of the DFHRPL concatenation in the CICS start-up job. If CICS program auto-install is not active, then you need to define a program resource for WBCSCUD.
- Move the WSBind file to a USS HFS (Hierarchical File System) pickup directory on the target z/OS system. The WSBind file is an EBCDIC binary file and therefore needs to be transmitted as binary to the target z/OS system. You can use the Remote System Explorer facilities of WebSphere Developer to copy this. But first, you need to tell WebSphere Developer that files with file extensions of wsbind are to be handled as binary. To enable this, bring up the Preferences dialog. Select Remote Systems from the list on the left and then add a new file type of *.wsbind.
For that file type, specify Binary as the file transfer mode.
Figure 14. WSBind - binary
- The CICS PIPELINE resource contains a reference to a pickup directory. Define or use an existing PIPELINE resource that references the pickup directory where you copied the WSBind file to. When you install the pipeline or perform a scan, CICS will
read the WSBind files in that pickup directory and automatically define
and install WEBSERVICE and URIMAP resources that are associated with
those WSBind files. Figure 15 shows the PIPELINE definition for WKPIPE01 with a pickup directory of /u/dnet017/cwspickup/ where WSBind
files are placed for installation.
Figure 15. PIPELINE definition
Figure 16 shows a WEBSERVICE resource that was created and installed from scanning the WKPIPE01 pipeline, where there was a WBCSCUSD.wsbind file in the associated pickup directory. It shows a relationship to program WBCSCUST (the existing application) and an auto
generated URIMAP ($308350).
Figure 16. WEBSERVICE resource
Figure 17 shows the definition for the autogenerated URIMAP, $308350. It shows a path of /wdz/CustInquiry, which was taken from the WSBind file. When a request comes into CICS with a local URI of /wdz/CustInquiry, this URIMAP definition will match, and the request gets associated with WEBSERVICE WBCSCUSD, which has a reference to the WSBind file. The WSBind file contains the name of the conversion program that will be invoked by CICS Web services.
Figure 17. URIMAP definition
|
Task 4. Test the CICS-based service
To test the CICS-based service that was deployed, you can use the Web
Services Explorer tool of WebSphere Developer.
- Select WBCSCUST.wsdl from the cicsws z/OS Local Project. Right-click, and
select Web Services->Test with WebServices Explorer.
- The Web Services Explorer launches in a Web browser view. Notice in the Status section that WBCSCUST.wsdl was successfully opened. In the Actions section you will also see that a WBCSCUSTOperation operation is available (Figure 18). Click on the link for the WBCSCUSTOperation operation (alternatively, you can click on the + sign beside WBCSCUSTBinding from the Navigator view).
Figure
18. Web Services Explorer
- Notice in Figure 19 that the Actions section is now replaced with information about the WBCSCUSTOperation operation and the parameters it takes. It also lists the endpoint associated with this request. Enter a value of 8 for CustNo and click Go to invoke the operation
Figure
19. WBCSCUSTOperation parameters
Figure 20 shows the results that are displayed in the Status view.
Figure 20. Results of WBCSCUSTOperations
Conclusion
You have seen how you can easily use the XML Services for the Enterprise capability of WebSphere Developer for zSeries V6 to transform an existing CICS
COBOL application into a Web service, and test the CICS-based service. The WebSphere Developer-generated WSDL file can be used as a starting point to create the clients that will access the CICS-based service.
Download | Description | Name | Size | Download method |
|---|
| Code sample artifacts | wdzcws.zip | 2KB | FTP|HTTP |
|---|
Resources Learn
Get products and technologies
-
Build your next development project with
IBM
trial software, available for download directly from developerWorks.
Discuss
About the author | | | Wilbert Kho is a Consulting Certified Software IT Specialist at IBM. He works on the Americas zSeries WebSphere team. His expertise includes application transformation tools like WebSphere Studio Asset Analyzer and WebSphere Developer for zSeries. He has over 20 years experience in the IT industry and has a B.S. Electrical Engineering degree from the University of the Philippines, a M.S. Computer Science from Northern Illinois University, and a M.B.A. from the University of Phoenix. |
Rate this page
| |
