IBM WebSphere Developer Technical Journal: Developing a CICS-based Web service with WebSphere Studio Enterprise Developer and SOAP for CICS

This article shows you how to adapt an existing CICS® COBOL application using IBM® WebSphere® Studio Enterprise Developer V5.1.1 so that it can be accessed as a Web service using the SOAP for CICS feature of CICS Transaction Server for z/OS® V2. It discusses how to test and invoke the Web service using Java™ and Microsoft® .NET based clients.

Introduction

In this tutorial, you will adapt an existing CICS COBOL application using the XML Enablement Tool facility of IBM WebSphere Studio Enterprise Developer (hereafter referred to as Enterprise Developer) so that it can be accessed as a Web service through the SOAP for CICS feature of CICS Transaction Server for z/OS V2. After adapting the existing CICS COBOL application, you will use Enterprise Developer to create the Web Services Description Language (WSDL) file that describes the CICS-based Web service. Next you will explore the Java-based Web Services Explorer tool in Enterprise Developer to test the Web service described in the WSDL file. Finally, you will take that WSDL file and generate proxies for consumption by a C# client running in the Microsoft .NET Framework.

This article does not cover the specifics of using WebSphere Studio, but assumes that you know how to navigate WebSphere Studio Enterprise Developer and are familiar with concepts of workspaces, perspectives, editors, and views. It is also not an introductory course on CICS, COBOL, Web services, or C#, and assumes that you have a working knowledge of developing these type of applications. This article also does not provide extensive coverage of Simple Object Access Protocol (SOAP) for CICS and Microsoft .NET. See the Resources section if you are interested in learning more on those topics.

The goal of this tutorial is to demonstrate how to adapt an existing CICS COBOL application into a Web service, using the tools in Enterprise Developer to:

  • Create and deploy adapter code (referred to later as a message adapter) that will run in a SOAP for CICS environment.
  • Create and describe the CICS-based Web service using a Web Services Description Language (WSDL) file. This Web service can be consumed by either Java- or Microsoft .NET-based development tools to create Java- or Microsoft .NET-based clients.

What you need to get started

Before starting, you need WebSphere Studio Enterprise Developer V5.1.1 and the Microsoft .NET Framework SDK V1.1. You also need access to a CICS Transaction Server for a z/OS V2 system that has the SOAP for CICS feature installed. The Microsoft .NET Framework SDK V1.1 is available from the (Microsoft Developer Network) at no charge and is used to demonstrate access to a CICS-based Web service from a Microsoft .NET client. Make sure that you get the SDK and not just the runtime framework.

The examples in this tutorial use a z/OS V1R4 system called DEMOMVS that is running CICS Transaction Server for z/OS V2R3 with the SOAP for CICS feature enabled. In addition, the z/OS components of Enterprise Developer are also installed and enabled.

Artifacts that you need to work through this tutorial are contained in the wseds4c.zip file provided as a download with this article. Put it in the \wseds4c\artifacts subdirectory. For the rest of this tutorial, I will refer to this as the artifacts directory.


WebSphere Studio Enterprise Developer

WebSphere Studio Enterprise Developer V5.1.1 facilitates the development of both Java- and z/OS-based applications. 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, Enterprise 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 enablement tool 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 this, the XML enablement tool generates the following set of artifacts (see Figure 1):

  1. 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.
  2. Output converter - COBOL program that takes the COBOL data results returned from the existing COBOL application and maps them to an XML document.
  3. Driver program - Template COBOL program that shows how the input and output converters can be used to interact with the existing COBOL application. This program must be modified before it can be run.
  4. Input document schema definition - XML schema that describes the incoming XML document for processing by the input converter.
  5. Output document schema definition - XML schema that describes the outgoing XML document produced by the output converter.
Figure 1. XML Enablement in WebSphere Studio Enterprise Developer
Figure 1. XML Enablement in WebSphere Studio Enterprise Developer

The input converter, output converter, and the customized driver program together form the adapter code that interfaces with the existing COBOL application and enables that COBOL application (with no modification) to effectively consume and produce XML documents. This adapter code becomes the message adapter to which SOAP for CICS passes control when fulfilling a Web service request for the existing CICS COBOL application.


SOAP for CICS

SOAP for CICS enables existing CICS Transaction Server for z/OS V2 systems to handle inbound and outbound SOAP requests. It lets existing CICS applications handle service requests, effectively making them service providers. You can also write new CICS applications that make service requests to Web services hosted on other systems. The SOAP requests are transported using either HTTP (Hypertext Transfer Protocol) or WebSphere MQ. A SOAP for CICS pipeline processes these requests (Figure 2), which eventually passes the SOAP body containing the XML request to a message adapter. The message adapter maps the XML request to a CICS COMMAREA that is then passed to an existing CICS application. The message adapter also maps any data returned in COMMAREA format to XML and sends this XML response back to the SOAP for CICS pipeline process. The resultant XML response forms part of the SOAP response body, which is returned to the SOAP client that initiated this request.

Figure 2. SOAP for CICS
Figure 2. SOAP for CICSEnterprise Developer

Overview of development tasks

To complete this tutorial you will perform the following tasks:

  1. Import a COBOL data declaration into a z/OS Local Project
  2. Use the XML Enablement tool to generate the message adapter and XML schemas
  3. Build and deploy the message adapter to CICS on z/OS
  4. Create the WSDL describing the CICS-based Web service
  5. Use the Web Services Explorer to test the CICS-based Web service
  6. Use the Microsoft .NET WSDL tool to generate C# proxy for the CICS based Web service
  7. Create, compile, and execute a simple Microsoft .NET client.

This article was developed and tested on a Windows XP workstation connected to the z/OS DEMOMVS system. The rest of this tutorial assumes you have started Enterprise Developer and are familiar with the use of its major components. Parts of the tutorial require that you have established connectivity to a z/OS system that contains a running CICS Transaction Server for z/OS V2 region enabled with SOAP for CICS. In the development and testing of this tutorial, I communicated with a CICS system named CICSA running on DEMOMVS.


Task 1. Import a COBOL data declaration into a z/OS local project

In this first task, you import an existing CICS COBOL application into a z/OS local project. The XML Enablement tool of Enterprise 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.

WBCSCUST is a relatively simple CICS COBOL application with no database interactions and therefore should be easy to build and deploy on your target z/OS system. To perform this tutorial using WBCSCUST, you must build and deploy it to a CICS region on your target z/OS system.

  1. From the z/OS Projects perspective, create a z/OS local project called CICSWS using the Local Project creation wizard. Accept the rest of the default values and select Finish.
    Figure 3. Creating a z/OS Local Project
    Figure 3. Creating a z/OS Local Project
  2. Import WBCSCUST.cbl from the artifacts directory to the CICSWS local project that you just created.

Task 2. Use the XML Enablement tool to generate the message adapter and XML schemas

Next, use the Generate XML converter wizard to generate the COBOL programs that make up the SOAP for CICS message adapter for WBCSCUST. You also generate the XML schemas that describe the input and output XML messages.

  1. Right-click WBCSCUST.cbl from the CICSWS local project, and select Enable XML => Generate XML converter to launch the Generate XML converter wizard.
  2. On the File selection panel, verify that the source file WBCSCUST.cbl is taken from the CICSWS local project. Check the box that instructs the wizard to generate the converters and driver to one physical file. You want this in most cases because it simplifies the build and deployment of the adapter code to your target z/OS system. For deployment to SOAP for CICS as a message adapter, this is what we want to do. Modify the name of the input converter file so that the file name is eight characters or less. For this tutorial, I specified a name of WBCSCUSD.cbl. Finally, I modified the file names for both the input and output message XSD files so that the first seven characters match the first seven characters of the input converter file name. Use Figure 4 as a guide.
    Figure 4. Specifying file options for Generate XML converter wizard
    Figure 4. Specifying file options for Generate XML converter wizard
    Click Next to continue.
  3. On the XML converter options panel, specify a program name that is seven characters or less. This will be used by the wizard as part of the program name when it generates the COBOL converters and driver. In this tutorial, I specified a program name of WCUST. The wizard generates a COBOL driver program named WCUSTD, and a COBOL input converter named WCUSTI. For the driver type, select CICS SOAP from the drop-down list since we are generating the message adapter that will be deployed to a SOAP for CICS environment. For the inbound namespace, change WBCSCUSTI to WBCSCUSI, that is, remove the "T". Do the same change for the outbound namespace by removing the "T" from WBCSCUSTO. Accept the defaults for the rest of the options, as shown in Figure 5.
    Figure 5. Specifying XML converter options
    Figure 5. Specifying XML converter options
    Click Next to continue.
  4. On the Data structures panel, select the input and output data structures that will be mapped to the input and output XML messages respectively. Remember that the existing program WBCSCUST takes as input a customer number and returns information about the customer. Therefore, I selected the field CUSTNO in the DFHCOMMAREA data structure as the input. For the output, I selected the complete DFHCOMMAREA data structure, as shown in Figure 6:
    Figure 6. Selecting data structures for conversion
    Figure 6. Selecting data structures for conversion
    Click Finish to generate the COBOL converters and driver, and the XML schemas that describe the input and output XML messages.
  5. Once the generation is complete, verify that your CICSWS project contains three additional artifacts: WBCSCUSD.cbl, WBCSCUSI.xsd, and WBCSCUSO.xsd, as shown in Figure 7.
    Figure 7. Artifacts generated by the Generate XML converter Wizard
    Figure 7. Artifacts generated by the Generate XML converter Wizard

Task 3. Build and deploy the message adapter to CICS on z/OS

In this task, you modify the generated driver program so that it will invoke the correct existing program and can be built correctly. You will then build and deploy it. One of the artifacts generated in the previous task is WBCSCUSD.cbl, a physical file containing the COBOL driver program, input converter, and output converter. We asked the Generate XML converter wizard to generate these to a single physical file to facilitate the build and deployment to z/OS. You will be working in the z/OS Projects perspective and making changes to WBCSCUSD.cbl.

  1. From the z/OS Projects view, double-click on WBCSCUSD.cbl from the CICSWS project. This brings up the z/OS LPEX Editor. You can use the Outline view (Figure 8) to understand the structure of WBCSCUSD and navigate to different parts of this application. The only part of WBCSCUSD that you want to modify is the driver, which has the Program-Id of WCUSTD. You can study the other parts like the input (WCUSTI) and output (WCUSTO) converters to appreciate the effort and time saved by using the Generate XML converter Wizard, but do not modify these.
    Figure 8. Editing WBCSCUSD.cbl using the z/OS LPEX Editor
    Figure 8. Editing WBCSCUSD.cbl using the z/OS LPEX Editor
  2. Using the Outline view, expand the Data Division of WCUSTD until you see its Local-Storage Section. Scroll through the Outline view until you see DFHCOMMAREA. Select DFHCOMMAREA to position the editor at DFHCOMMAREA (see Figures 9 and 10).
    Figure 9. WCUSTD Local-Storage
    Figure 9. WCUSTD Local-Storage
    Figure 10. DFHCOMMAREA in Local-Storage Section
    Figure 10. DFHCOMMAREA in Local-Storage Section
  3. Change DFHCOMMAREA to CustInterface. Since this is a CICS COBOL program, it has to be processed by the CICS translator. The CICS translator will insert a declaration for DFHCOMMAREA in the Linkage Section of WCUSTD, which would result in a compilation error because a declaration for DFHCOMMAREA has already been made in the Local-Storage Section. Therefore, you need to change the Local-Storage Section declaration of DFHCOMMAREA. Since we are already changing the name, it makes sense to give it a more descriptive name like CustInterface, as shown in Figure 11.
    Figure 11. CustInterface
    Figure 11. CustInterface
    Press Ctrl+S to save your changes.
  4. There are three other places within WCUSTD where DFHCOMMAREA is referenced that we need to change to CustInterface:
    • The call to the existing business program, which was generated as CURRBUS (see Listing 2).
    • The call to the input converter WCUSTI (see Listing 3).
    • The call to the output converter WCUSTO (see Listing 4).
    Using the editor, replace DFHCOMMAREA with CustInterface. In addition, replace CURRBUS with WBCSCUST, which is the name of the existing program. Make sure you only change the references within WCUSTD.

    Listing 2. Execute current business program

    * -------------------------------------------------------------
    *               Execute Current Business Program      
    * -------------------------------------------------------------
               exec cics link
                program  ('CURRBUS')
                commarea (DFHCOMMAREA)
               end-exec

    Listing 3. Call to input converter WCUSTI

    w-inbound-conversion.
         call 'WCUSTI'
           using
             DFHCOMMAREA
             w-xml-int-len
             w-xml-int-txt
             omitted
    *   w-optional-feedback-code
           returning
             w-converter-return-code

    Listing 4. Call to output converter WCUSTO

    w-outbound-conversion.
         call 'WCUSTO'
           using
             DFHCOMMAREA
             w-xml-int-len
             w-xml-int-txt
             omitted
    *   w-optional-feedback-code
           returning
             w-converter-return-code

    Press Ctrl+S to save the changes.
  5. Now that you have made the required changes to the driver program, WCUSTD, you are ready to build and deploy the message adapter to z/OS. Remember that the message adapter is composed from the driver program, input converter, and output converter, and is contained within one physical file, WBCSCUSD.cbl. To build the message adapter, you need to compile the WBCSCUSD program and link it into an executable load module. On my DEMOMVS system, I installed IBM Enterprise COBOL for z/OS V3.3, which supports an integrated CICS translator. This means that only a COBOL compile step is needed instead of the usual steps of doing a CICS translation followed by a COBOL compile.

    There are different ways of moving the WBCSCUSD COBOL source program to the target z/OS system so that it can be built and deployed to a CICS system; Enterprise Developer can facilitate this. I will not walk you through every detail of using Enterprise Developer but will describe the things you need to do at a high level. Subsequent steps assume you have used Enterprise Developer to connect to a z/OS system and have copied WBCSCUSD.cbl from the CICSWS local project to a member of a library on your target system. In testing this tutorial, I connected to the DEMOMVS system and copied WBCSCUSD.cbl to a MVS library named DNET017.CICSWS.COBOL.

  6. After connecting to the target z/OS system, create a z/OS MVS project and add the WBCSCUSD program from the z/OS system to that project. In this example, I created a z/OS MVS project named CICSWZ and I added member WBCSCUSD from dataset DNET017.CICSWS.COBOL to CICSWZ (see Figure 12). I have included the properties file for CICSWZ project for your reference; this is CICSWSZ_properties.xml in the artifacts directory.
    Figure 12. CICSWZ MVS project
    Figure 12. CICSWZ MVS project
  7. Right-click WBCSCUSD from the CICSWZ project and select Generate JCL => For Compile Link to generate a job that you can submit to the target z/OS system. The CICSWZ project has been set up so that the job generated will contain steps to compile the program using the integrated CICS translator and link this into an executable load module.
  8. Once generation is complete, an additional artifact is displayed in the CICSWZ project, which is the compile and link job. In this example, the job generated is also named WBCSCUSD and is contained in dataset DNET017.STEW.JCL. You can double-click on this job to view it in the z/OS LPEX Editor and make additional changes (Figure 13).
    Figure 13. WBCSCUSD job to compile and link WBCSCUSD
    Figure 13. WBCSCUSD job to compile and link WBCSCUSD
  9. After you save your changes, submit the job using Enterprise Developer. You can then use the z/OS Job Monitor view to monitor the submitted job and view its results (Figure 14).
    Figure 14. Monitoring jobs with WebSphere Studio Enterprise Developer
    Figure 14. Monitoring jobs with WebSphere Studio Enterprise Developer
  10. Assuming the compile and link of WBCSCUSD was successful, you now have an executable load module that can be deployed to CICS. At a high level, these are things you need to do next:
    1. Copy the load module to a library that is part of the DFHRPL concatenation for the target CICS system.
    2. Define and install a PROGRAM resource for WBCSCUSD.
    For the DEMOMVS system that I used, I had to copy the WBCSCUSD load module to a data set named USER.LOADLIB and activate a PROGRAM resource for it on the CICSA CICS system. The procedures you will use for your specific installation may vary. When you conclude this step, the SOAP for CICS message adapter for the existing program WBCSCUST is now ready to process service requests. At this point, you can disconnect Enterprise Developer from your target z/OS system.

Task 4. Create the WSDL describing the CICS-based Web service

At the completion of the previous task, you had successfully deployed a message adapter named WBCSCUSD that will interact with an existing program named WBCSCUST. WBCSCUSD effectively enables WBCSCUST to consume and produce XML messages. In conjunction with SOAP for CICS, this application can now be accessed as a Web service. What we need to do next is describe this CICS-based Web service so it can be published and discovered. To do this, we will create a Web Services Description Language (WSDL) file. Figure 15 outlines the steps you use in Enterprise Developer to create the WSDL. Once the WSDL is created, you will use the Web Service Explorer tool in the next task to test it.

Figure 15. Creating a WSDL for a CICS-based Web service
Figure 15. Creating a WSDL for a CICS-based Web service
  1. In the z/OS Projects view, select the CICSWS project and press Ctrl+N to bring up the New wizard. On the Select a wizard panel, select Web services from the left pane, and in the right pane select WSDL (see Figure 16). Click Next to continue.
    Figure 16. Creating a new WSDL file
    Figure 16. Creating a new WSDL file
  2. On the New WSDL File panel, verify that CICSWS is the parent folder and specify CustInfo.wsdl as the file name. Click Next to continue.
  3. On the Options panel, specify a definition name of CustInfo and select soap http://schemas.xmlsoap.org/wsdl/soap as an additional namespace URI to be included (Figure 17). The wsdl namespace contains the definitions for the WSDL elements. The soap and xsd are standard namespace definitions that are used for specifying SOAP-specific information as well as data types.
    Figure 17. Specifying Options for CustInfo.wsdl
    Figure 17. Specifying Options for CustInfo.wsdl
    Click Finish to complete the creation of the WSDL file.
  4. After creating the WSDL file, the New WSDL File wizard will bring up a WSDL editor so that you can complete your description of the Web service. There is more than one editor associated with WSDL files. By default, Enterprise Developer has the Basic JCA WSDL Editor defined as the default editor for WSDL files. This editor is used when you are performing JCA (J2EE Connector Architecture) related development. In this tutorial we will use another editor called the WSDL Editor.

    To tell which editor you are using, look at the number of tabs associated with it. The Basic JCA WSDL Editor has six tabs while the WSDL Editor has only two (see Figures 18 and 19). We will be editing the WSDL file using the Graph view of the WSDL Editor. If the New WSDL File wizard placed you into the Basic JCA WSDL Editor, you have to close it and reopen the CustInfo.wsdl file using the WSDL Editor.

    Figure 18. Basic JCA WSDL Editor
    Figure 18. Basic JCA WSDL Editor
    Figure 19. WSDL Editor
    Figure 19. WSDL Editor
  5. Make sure you are working in the Graph view of the WSDL Editor (Figure 19). Now we will start our description of the WBCSCUSD Web service. First we need to define a portType, which is an abstract set of operations supported by one or more endpoints. The port type can be compared to a function library or module in a traditional programming language. With your cursor positioned within the Port Types section of the Graph view, right-click and select Add Child => portType, give the new Port Type the name CustInfo and click OK (see Figures 20 and 21).
    Figure 20. Adding a Port Type
    Figure 20. Adding a Port Type
    Figure 21. CustInfo Port Type
    Figure 21. CustInfo Port Type
  6. Having defined a Port Type, we will now define the operations that are associated with it. An operation is an abstract definition of an action supported by the service. For this tutorial, we will define just one operation. Right-click on the CustInfo port type and select Add Child => operation; give the new operation the name getCustInfo and click OK (see Figures 22 and 23).
    Figure 22. Adding an operation to CustInfo
    Figure 22. Adding an operation to CustInfo
    Figure 23. getCustInfo Operation
    Figure 23. getCustInfo Operation
  7. An operation is usually associated with input and output messages. The operation could be one-way, where it receives a message but does not return a response. The operation could also be a request-response, where it receives a request and returns a response. Recall that our CICS-based Web service takes as input a customer number and returns information about that customer. We will therefore define input and output messages that will be associated with the getCustInfo operation. To do this, right-click on getCustInfo operation and select Add Child -> input (see Figure 24).
    Figure 24. Associating input to getCustInfo
    Figure 24. Associating input to getCustInfo
    Repeat the process and add an output to getCustInfo. At this point, you should see something similar to Figure 25.
    Figure 25. CustInfo.wsdl with Port Type defined
    Figure 25. CustInfo.wsdl with Port Type defined
    Pres Ctrl+S to save your changes.
  8. Having defined input and output for the getCustInfo operation, next we associate messages with the input and output. A message is an abstract definition of the data being communicated. We will define a message to be associated with the input request to the Web service, and a message to be associated with the output response from the Web service. To do this, right-click on input from the getCustInfo operation, and select Set Message.... On the Specify Message panel, select Create a new message and accept the default message name of getCustInfoRequest. Click Finish to specify the message. Use Figures 26 and 27 as a guide.
    Figure 26. Defining the Input Message
    Figure 26. Defining the Input Message
    Figure 27. getCustInfoRequest Message
    Figure 27. getCustInfoRequest Message
    Repeat the process for output and accept the default message name of getCustInfoResponse. At this point you should see something similar to Figure 28.
    Figure 28. CustInfo.wsdl with Messages defined
    Figure 28. CustInfo.wsdl with Messages defined
    Press Ctrl+S to save your changes.
  9. Having defined the messages associated with the getCustInfo operation, we will now define the parts that make up those messages. A message can be made up of one or more parts. For this tutorial, the getCustInfoRequest and getCustInfoResponse messages will each comprise one part. Right-click the getCustInfoRequest message and select Add Child => part; give the part the name CustNo and click OK (see Figures 29 and 30).
    Figure 29. Defining a message part
    Figure 29. Defining a message part
    Figure 30. CustNo Part
    Figure 30. CustNo Part
    Repeat the process to define a part for the getCustInfoResponse message and give the part the name CustData. At this point, you should see something similar to Figure 31.
    Figure 31. CustInfo.wsdl with Parts defined
    Figure 31. CustInfo.wsdl with Parts defined
    Press Ctrl+S to save your changes.
  10. Having defined the parts, we now have to define the elements that make up those parts. This is where we will use the XML schemas that were generated by the Generate XML converter wizard when you performed Task 2. Right-click on CustNo part and select Set Element.... On the Specify Element panel, select Import element from a file and click the Browse... button (see Figures 32 and 33).
    Figure 32. Setting an Element for CustNo
    Figure 32. Setting an Element for CustNo
    Figure 33. Importing an Element
    Figure 33. Importing an Element
  11. On the Select File panel, select WBCSCUSI.xsd from the CICSWS project. WBCSCUSI.xsd is the input XML schema that the Generate XML converter wizard generated. Click OK to select it. Back on the Specify Element panel, notice that the element dfhcommarea from WBCSCUSI.xsd has been selected. Click Finish to specify the element for CustNo (see Figures 34 and 35).
    Figure 34. Selecting WBCSCUSI.xsd
    Figure 34. Selecting WBCSCUSI.xsd
    Figure 35. Importing dfhcommarea
    Figure 35. Importing dfhcommarea
    Repeat the process to define the element for the CustData part, selecting WBCSCUSO.xsd as the XML schema to import. At this point, you should see something similar to Figure 36. Notice that the CustNo and CustData parts now reference dfhcommarea. Press Ctrl+S to save your changes.
    Figure 36. CustInfo.wsdl after referencing XML schemas
    Figure 36. CustInfo.wsdl after referencing XML schemas
  12. So far, we have defined the abstract interface for the CICS-based Web service. We will be defining the concrete communications protocol and address that can be used to access the Web service for the remainder of this task. Next we will define the binding for the service, using the binding wizard. To launch the binding wizard, click the binding wizard button Binding wizard button in the workbench toolbar.
  13. On the Specify Binding Details panel, select Generate a new binding. Use CustInfoBinding as the name of the binding. Select tns:CustInfo as the port type (there should only be one selection in the list). Select SOAP as the protocol. Finally, select document literal as the SOAP binding option; document literal is required for interoperability with Microsoft .NET. Use Figure 37 as a guide to complete this.
    Figure 37. WSDL Binding Details
    Figure 37. WSDL Binding Details
    Click Finish to complete the generation of the binding. At this point, you should see something similar to Figure 38.
    Figure 38. CustInfo.wsdl with Binding defined
    Figure 38. CustInfo.wsdl with Binding defined
    Press Ctrl+S to save your changes.
  14. Having defined the binding, the last thing we have to do is to define the service. This is where we define a communication endpoint for the service by specifying a port address for the binding. A service is a collection of one or more endpoints. For our tutorial, we only have one endpoint. In the Graph view of the WSDL Editor, position your cursor in the Services section, right-click and select Add Child => service; give the service the name CustInfoService and click OK to continue (see Figures 39 and 40).
    Figure 39. Defining a service
    Figure 39. Defining a service
    Figure 40. CustInfoService Service
    Figure 40. CustInfoService Service
  15. Right-click the CustInfoService you just defined, and select Add Child => port; give the port the name CustInfo (see Figures 41 and 42). You can think of this port as the concrete counterpart of the abstract port type CustInfo. Click OK to continue.
    Figure 41. Defining a Service Port
    Figure 41. Defining a Service Port
    Figure 42. CustInfo Port
    Figure 42. CustInfo Port
  16. Right-click the CustInfo port that you just defined, and select Set Binding... (Figure 43).
    Figure 43. Set Service Binding
    Figure 43. Set Service Binding
    On the Specify Binding panel, select Select an existing binding (there should only be tns:CustInfoBinding which would be preselected) and click Finish to associate the CustInfo port with the existing binding.
  17. We are almost done with describing the CICS-based Web service. The last thing we need to do is to specify the specific SOAP address, which will be in the form of an Uniform Resource Identifier (URI). Right-click the CustInfo port and select Add Extensibility Element => soap:address (see Figure 44).
    Figure 44. Adding a SOAP address to CustInfo port
    Figure 44. Adding a SOAP address to CustInfo port
  18. An element soap:address is created under the CustInfo port. Select soap:address to modify its location property. For this tutorial, I specified the URI http://demomvs.demopkg.ibm.com:8080/CICS/CWBA/DFHWSDSH/WBCSCUSD as the value for location. You should replace demomvs.demopkg.ibm.com:8080 with the IP address of your z/OS system and the IP port number where SOAP for CICS is listening for requests. The rest of the URI should be left as is unless the message adapter was deployed using a name different from WBCSCUSD; in that case, replace WBCSCUSD with the name you used. See Figure 45 for guidance.
    Figure 45. Specifying SOAP address location
    Figure 45. Specifying SOAP address location
    Press Ctrl+S to save your changes. We have finished describing the CICS-based Web service, WBCSCUSD, and the description is now contained in the CustInfo.wsdl WSDL file. You can now use this WSDL file to generate the proxies needed to develop either a Java or Microsoft .NET based client.

Task 5. Use the Web services Explorer to test the CICS based Web service

In this task, we will use the Web Services Explorer tool in Enterprise Developer to test our CICS-based Web service.

  1. On the CICSWS project, right-click CustInfo.wsd and select Web Services => Test with Web Services Explorer.
  2. The Web Services Explorer launches in a Web browser view. The Web Services Explorer has three major sections: the Navigator, Actions, and Status. Notice in the Status section that CustInfo.wsdl successfully opened. In the Actions section you also see that a getCustInfo operation is available. Click on the link for the getCustInfo operation (Figure 46).
    Figure 46. CustInfo.wsdl opened by the Web Services Explorer Tool
    Figure 46. CustInfo.wsdl opened by the Web Services Explorer Tool
  3. Notice that the Actions section is now replaced with information about the getCustInfo 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.
  4. If you correctly built and deployed the message adapter WBCSCUSD and the existing program WBCSCUST, and you corrently configured and started the SOAP for CICS on your z/OS system , you should see results in the Status section that is similar to that in Figure 47. If there are any errors, click on the Source link to view the SOAP response envelope for any error messages contained in the SOAP body.
    Figure 47. Results from getCustInfo for Customer # 8
    Figure 47. Results from getCustInfo for Customer # 8
    You can test with customer numbers from 1 to 10. After you are done testing, you can close the Web browser.

Task 6. Use the Microsoft .NET WSDL tool to generate a C# proxy for the CICS-based Web service

So far, you have successfully built and deployed a SOAP for CICS message adapter for an existing CICS COBOL application, effectively exposing this application as a Web service. You have also successfully described and tested this CICS Web service using WSDL and the Web Services Explorer tool. You completed these activities in a Java-based development environment in Enterprise Developer. The last two tasks in this tutorial demonstrate how to achieve interoperability with Web services. We will take the WSDL that was created in Task 4 and use it in a Microsoft .NET environment.

  1. The Microsoft .NET Framework SDK V1.1 contains a WSDL Tool (wsdl.exe) that can generate proxies for use by clients to access a Web service. This tool takes WSDL and XML schema files as input, and can generate proxy code in either C# (CS), Visual Basic (VB), JScript (JS), or Visual J# (VJS). In this tutorial, we will use this tool to generate C# proxy code.

    Since I only have the SDK installed, I will be demonstrating this using the command line. Before proceeding, create a directory called CustInfoClient on your disk. Using Enterprise Developer, export the CustInfo.wsdl, WBCSCUSI.xsd, and WBCSCUSO.xsd files to that directory.

  2. Issue the following command from the CustInfoClient directory (assuming that the Microsoft .NET SDK bin and Framework runtime directories are defined in the PATH environment variable):

    wsdl /nologo CustInfo.wsdl WBCSCUSI.xsd WBCSCUSO.xsd

  3. The CustInfoClient directory should contain one resultant file, CustInfoService.cs (see Listing 5 for a sample of this code). This is the C# proxy to the CICS-based Web service.

    Listing 5

    using System.Diagnostics;
    using System.Xml.Serialization;
    using System;
    using System.Web.Services.Protocols;
    using System.ComponentModel;
    using System.Web.Services;
    
    /// <remarks/>
    [System.Diagnostics.DebuggerStepThroughAttribute()]
    [System.ComponentModel.DesignerCategoryAttribute("code")]
    [System.Web.Services.WebServiceBindingAttribute(Name="CustInfoBinding", 
    	Namespace="http://example.com")]
    public class CustInfoService : System.Web.Services.Protocols.
    	SoapHttpClientProtocol {
    
    /// <remarks/>
    public CustInfoService() {
    this.Url = "http://demomvs.demopkg.ibm.com:8080/CICS/CWBA/DFHWSDSH/WBCSCUSD";
    }
    
    /// <remarks/>
    [System.Web.Services.Protocols.SoapDocumentMethodAttribute("http://example.com/
    	getCustInfo", 
    Use=System.Web.Services.Description.SoapBindingUse.Literal, 
    ParameterStyle=System.Web.Services.Protocols.SoapParameterStyle.Bare)]
    [return: System.Xml.Serialization.XmlElementAttribute("dfhcommarea", 
    Namespace="http://www.WBCSCUSO.com/schemas/WBCSCUSOInterface")]
    public DFHCOMMAREA1 getCustInfo([System.Xml.Serialization.XmlElementAttribute
    (Namespace="http://www.WBCSCUSI.com/schemas/WBCSCUSIInterface")] DFHCOMMAREA 
    	dfhcommarea) {
    object[] results = this.Invoke("getCustInfo", new object[] {
    dfhcommarea});
    return ((DFHCOMMAREA1)(results[0]));
    }
  4. We will now generate a library that can be referenced by C# clients. Issue the following command from the CustInfoClient directory:

    csc /target:library CustInfoService.cs

    This command invokes the Microsoft C# compiler and produces a CustInfoService.dll file, which is a dynamic link library.

Task 7. Create, compile, and execute a simple Microsoft .NET client

In this task, you will "create", compile, and execute a simple Microsoft .NET client written in C#. You can create your own client, although I have supplied a sample C# client to put you on the fast track.

  1. Copy the CustInfoClient.cs file from the artifacts directory to the CustInfoClient directory.
  2. Edit the CustInfoClient.cs file and examine it to understand how the proxy is invoked (see Listing 6).

    Listing 6

    using System;
    // references CustInfoService.dll
    // build using: csc.exe CustInfoClient.cs /reference:CustInfoService.dll
    
    public class CustInfoClient {
    public static void Main() {
    
    // Instantiate the CustInfo web service proxy
    // CustInfoService defined in CustInfoService.dll
    CustInfoService proxy = new CustInfoService();
    
    // Instantiate the request document
    // DFHCOMMAREA defined in CustInfoService.dll
    DFHCOMMAREA request = new DFHCOMMAREA();
    
    // Instantiate the response document
    // DFHCOMMAREA1 defined in CustInfoService.dll
    DFHCOMMAREA1 response = new DFHCOMMAREA1();
    
    Console.WriteLine("Invoking CICS routine via SOAP over .NET.");
    
    string message = null;
    try {
    request.CustNo = 8;
    response = proxy.getCustInfo(request);
    message = response.CustNo.ToString();
    message = String.Concat("Details for customer # ", message);
    Console.WriteLine(message);
    WriteMessage(String.Concat(response.LastName, ", ", response.FirstName));
    WriteMessage(response.Address1);
    WriteMessage(response.City);
    WriteMessage(String.Concat(response.State, ", ", response.Country));
    message = response.RetCode.ToString();
    message = String.Concat("Return code from request: ", message);
    Console.WriteLine(message);
    message = "Done invoking CICS COBOL based web service using SOAP."; 
    WriteMessage(message);
    }
    catch (Exception e) {Console.WriteLine("Threw general exception: {0}", e);}
    }
    private static void WriteMessage(string message) {
    Console.WriteLine("Server returns: {0}", message);
    }
    }
  3. Issue the following command from the CustInfoClient directory, which create a Windows executable, CustInfoClient.exe:

    csc CustInfoClient.cs /reference:CustInfoService.dll

  4. Issue the following command from the CustInfoClient directory to run the client:

    CustInfoClient.exe

    You should see something similar to Figure 48.
    Figure 48. Running CustInfoClient - Microsoft .NET Client
    Figure 48. Running CustInfoClient - Microsoft .NET Client

Conclusion

This article walked you through how to adapt an existing CICS COBOL application to be exposed as a Web service that can be accessed by either Java or Microsoft .NET clients. Using the SOAP for CICS feature of CICS Transaction Server for z/OS V2, it demonstrated how you can use WebSphere Studio Enterprise Developer V5.1.1 to transform your z/OS- based CICS COBOL applications. These existing critical business applications can now form part of your Service Oriented Architecture (SOA).


Download

DescriptionNameSize
Code sampleSOAP4CICS.zip  ( HTTP | FTP )4 KB

Resources

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=16282
ArticleTitle=IBM WebSphere Developer Technical Journal: Developing a CICS-based Web service with WebSphere Studio Enterprise Developer and SOAP for CICS
publish-date=09152004