Implement a Web service provider and requester using native CICS APIs and IBM Rational Developer for System z

IBM® Rational® Developer for System z™ integrates the IBM® CICS® Web Services Assistant (DFHWS2LS) to help streamline your development of CICS applications based on existing Web service descriptions (WSDL). This article shows you how to develop both a CICS Web service provider and requester with the Rational Developer for System z tool.

Teodoro Cipresso (cipresso@us.ibm.com), Software Developer, IBM Japan

Teodoro CipressoTed has worked with enterprise customers for nearly eight years on the creation of tools that modernize mainframe systems and sub-systems through XML and Web-enablement of critical business assets. Since joining IBM in June 2000, he's worked on XML support for COBOL and PL/I as well as enterprise Web service enablement tools. Currently, Ted is an Advisory Software Engineer on the Enterprise Service Tools component of IBM Rational Developer for System z and a graduate student of Computer Science at San Jose State University. His areas of research include: software reverse engineering, design recovery, anti-reverse engineering, and software security.



Gary Mazo (mazo@us.ibm.com), Team Lead, Enterprise Service Tools, IBM Japan

Gary MazoGary Mazo has over 20 years of software development experience. Since joining IBM in 1987, he worked on projects ranging from writing parts of Fortran compiler to development of a graphics library for COBOL, to writing an MS Windows plugin for accessing remote file systems on MVS. Currently, Gary is part of a global team in charge of Enterprise modernization strategy, and its development and implementation in Rational Developer for System z.



01 April 2008

Introduction

IBM® Rational® Developer for System z™ integrates the IBM® CICS® Web Services Assistant (DFHWS2LS) to help streamline your development of CICS applications based on existing Web service descriptions (WSDL). You can develop two types of new applications: either a Web service provider or a Web service requester. This article shows you how to develop both a CICS Web service provider and requester with assistance from the Rational Developer for System z tool.

No special runtime is required, because both the implementations of the provider and requester execute in CICS itself using native Web service APIs. Rational Developer for System z improves on the usability of DFHWS2LS by providing a graphical interface and a template to help you generate provider and requester programs. The template programs help you use the Channels and Containers support introduced in CICS TS Version 3.1, which is needed for applications to interact with the CICS web services pipeline.

Existing calculator Web service description

This article includes a WSDL document that describes a calculator Web service. The service has several operations, and exposes simple functionality such as addition, multiplication, and division, as shown in Figure 1. The XML Schemas in the WSDL document, which describe the request and response messages, are not verbose, but do include the unbounded array construct. The Calculator.wsdl file is used in Rational Developer for System z to generate the language structures and template programs that form the basis of the implementation. CICS Web service applications implemented using the Web Services Assistant communicate via language structures with SOAP as the underlying transport.

Figure 1. Calculator Web service operations and messages
screen capture

Version of Rational Developer for System z used in this example

Rational Developer for System z Version 7.1 includes the Enterprise Service Tools perspective, which provides project-based development for Web services. There are many benefits to these "single-service" projects, one of which is that the Web service wizards remember previously specified generation options. This makes it possible for you to regenerate artifacts or develop them iteratively. More information on this feature is available in the product help. At this point, you should switch to the Enterprise Services Tools perspective, as shown in Figure 2.

Figure 2. Switch perspective
screen capture

Generating Web service provider artifacts using Rational Developer for System z

Included with this article is a zip file named WebServicesforCICSTopDownSample

Locate the Calculator.wsdl file in the extracted set of files and update the location URI to match the location of a running CICS TS (V3.1 or later) region. Update the location URI in the CalculatorBinding according to this pattern: http://your.system.ip:cics_tcpipservice_port/cics/services/calculator

It is now possible to proceed with generating the service provider artifacts, following these steps.

  1. In Rational Developer for System z, open the Enterprise Service Tools perspective
  2. Right-click in the EST Project Explorer and select New > Web Services for CICS project, as shown in Figure 3.
Figure 3. Create a new project
screen capture
  1. Give the project a suitable name (in this example, Calculator), as shown in Figure 4.
Figure 4. Name the project
screen capture
  1. On the next page, specify the Calculator.wsdl file that was included in the .zip file and click Finish, as shown in Figure 5.
Figure 5. Specify file to import
screen capture
  1. A new project should appear in the EST Project Explorer with the WSDL file located in the /Source directory, as shown in Figure 6.
Figure 6. The Calculator.wsdl file
screen capture
  1. Once there are source files in an EST Project Single-Service Project, you can generate Web service artifacts. To do so, right-click the Calculator project and select Generate Web Services for CICS Resources, as shown in Figure 7.
Figure 7. Generate artifacts
screen capture
  1. Specify options in the Launchpad dialog: accept the default Scenario of Create New Service Implementation (top-down) and the Conversion type of Interpretive XML Conversion, as shown in Figure 8.
Figure 8. Specify launch options
screen capture
  1. Specify the following options on the Application Properties tab of the DFHWS2LS wizard, as shown in Figure 9.
    • Application Type: Service Provider
    • Application language: COBOL
    • Program name: CALCPROV
    • Program interface: CHANNEL
    • Container name: CALCPROV

The options on this tab specify the details of the application that will implement the Web service description, either as a provider or a requester of the service (in this example, Service Provider here).

Figure 9. Application Properties options
screen capture
  1. Specify the following options on the Service Properties tab of the DFHWS2LS wizard, as shown in Figure 10:
    • Binding element: CalculatorBinding
    • Local URI: /cics/services/calculator

The options on this tab deal with which Binding in the WSDL document to implement. There is only one SOAP binding in the Calculator.wsdl file. Since you are implementing a provider, specify a URI under which your Web service will be visible to clients. Given your specified URI, your service will be located at: http://your.system.ip:cics_tcpipservice_port/cics/services/calculator

Figure 10. Service Properties options
screen capture
  1. Specify the following options on the Structures tab of the DFHWS2LS wizard, as shown in Figure 11.
    • Request file prefix: CALCI
    • Response file prefix: CALCO

These options determine the filenames of the languages structures generated from the XML schemas in the WSDL file.

Figure 11. Structures options
screen capture
  1. Specify the following options on the WSBind tab of the DFHWS2LS wizard, as shown in Figure 12.
    • WSBIND file name: CalculatorProvider
    • Log file name: CalculatorProvider

These options determine the filenames of the WSBind file and the Log file. The WSBind file will need to be placed in the pickup directory of a provider-mode PIPELINE (after completion of the wizard). The Log file provides verbose detail about the internal processing of the Web Services Assistant.

Figure 12. WSBind options
screen capture
  1. Specify the following option on the Template tab of the DFHWS2LS wizard, as shown in Figure 13.
    • Template file name: CALCPROV

This tab allows you to specify the filename of the generated application template. The template is intended to be used as a starting point to develop the new CICS Web service provider application. It contains sample logic to suggest a programming pattern for implementing a provider of a multi-operation Web service.

Figure 13. Template options
screen capture
  1. Click Finish to complete the wizard. The Calculator project will be populated with several artifacts, as shown in Figure 14. The artifacts in the Targets folder are the generated Web services artifacts with which to implement the Web service provider. In this example, six copybooks were generated.

The copybooks suffixed with "I" contain the language structures for the request data of the three operations (AddOperation, MultiplyOperation, and DivideOperation). Those suffixed with "O" contain the respective language structures for the response data. CALCPROV.cbl is the generated Web service provider template program. The next section will focus on how to complete its logic in the next section.

Figure 14. The populated Calculator project
screen capture

Implementing a Web service provider using the template

The provider template program CALCPROV.cbl is generated as a complete COBOL application with areas where the user should fill in the business logic. In the case where XML Schemas for a given operation (such as AddOperation) contain an unbounded array, additional coding is required to access the contents of these arrays, since they are stored in secondary containers. The process of working with secondary containers should become clear as the coding unfolds.

  1. The service provider program begins with some information that identifies it as CICS Web service provider implementation, as shown in Listing 1.
Listing 1. Identification Division
LINE    ----+-*A-1-B--+----2----+----3----+----4----+----5----+----6----+----7--
00000001       PROCESS CICS,NODYNAM,NSYMBOL(NATIONAL),TRUNC(STD)
00000002      *          *********************************************
00000003      *    *********************************************************
00000004      *  *************************************************************
00000005      *              New CICS TS 3.x Web Service Provider
00000006      *  *************************************************************
00000007      *    *********************************************************
00000008      *          *********************************************
00000009       IDENTIFICATION DIVISION.
00000010      *Begin Identification Divsion
00000011        PROGRAM-ID. 'CALCPROV'.
00000012        AUTHOR. WD4Z.
00000013        DATE-WRITTEN. 2/21/07 12:59 PM.
00000014      *End Identification Divsion
  1. For reasons that will soon become obvious, you declare some work variables in the local-storage section of the program, as shown in Listing 2.
Listing 2. Declare work variables
LINE    ----+-*A-1-B--+----2----+----3----+----4----+----5----+----6----+----7--
00000032        LOCAL-STORAGE SECTION.
00000033      *Begin Local-Storage Section
00000034      * *************************************************************
00000035      *                    Program Work Variables
00000036      * *************************************************************
00000045       1 WORK-INTEGER PIC S9(9) COMP-5.
00000046       1 WORK-COUNTER PIC 9(9)  BINARY.
00000047       1 WORK-FLOAT COMP-1.
00000048       1 WORK-DATA-LEN PIC 9(9) BINARY.
00000049       1 WORK-DATA-PTR POINTER.

The comments in the generated copybooks for the AddOperation (CALCI01.cpy) and MultiplyOperation (CALCO02.cpy) indicate that the data member that contains the operands to find the sum and product are located in a secondary container.

  1. In the linkage section, you define something that will allow for accessing the individual occurrences of those data members in the container. There are many ways to accomplish this, but you will use the most straightforward (not necessarily efficient) technique. This overlay allows for reading up to 512 operands from the request message, as shown in Listing 3.
Listing 3. Declare an overlay
LINE   ----+-*A-1-B--+----2----+----3----+----4----+----5----+----6----+----7--
0000069       LINKAGE SECTION.
0000070      *Begin Linkage Section
0000074      * We declare an overlay to access each element of the
0000075      * unbounded arrays present in the language structures within
0000076      * the copybooks CALCI01.cpy and CALCI02.cpy which were
0000077      * generated by DFHWS2LS. This saves manual address
0000078      * arithmetic and ensures we establish addressability within
0000079      * the compiler limit of 128mb for the linkage section.
0000080       1 CALCULATOR-OPERAND-OVERLAY.
0000081           5 OPERAND-INSTANCE OCCURS 512 TIMES
0000082             INDEXED BY OPERAND-INSTANCE-NDX PIC S9(9) COMP-5 SYNC.
  1. Within the template program, there are logical divisions for processing the inbound data (requests), and sending the outbound data (responses), based on the operation invoked by the client. For the AddOperation whose logical division begins on line 139, you fill out the logic for computing the SUM.
Listing 4. Logic to compute the sum
LINE    ----+-*A-1-B--+----2----+----3----+----4----+----5----+----6----+----7--
00000139      * -------------------------------------------------------------
00000140      *              Process Request Language Structure
00000141      * -------------------------------------------------------------
00000142           EVALUATE WS-OPERATION-NAME
00000143              WHEN OPERATION-NAME-1
00000150      * Get the container whose storage is organized as occurrences
00000151      * of the 01 level data item "CALCI01-additionXoperand"
00000152               EXEC CICS GET CONTAINER(additionXoperand-cont)
00000153                 SET(WORK-DATA-PTR)
00000154                 FLENGTH(WORK-DATA-LEN)
00000155                 RESP(COMMAND-RESP) RESP2(COMMAND-RESP2)
00000156               END-EXEC
00000157               PERFORM CHECK-CONTAINER-COMMAND
00000159      * Overlay the contiguous storage of the container with a
00000160      * data structure that allows us to easily access each
00000161      * occurrence of the array.
00000162               SET ADDRESS OF CALCULATOR-OPERAND-OVERLAY
00000163                 TO WORK-DATA-PTR
00000165      * Loop through array occurrences and compute SUM for
00000166      * "AddOperation".
00000167               INITIALIZE WORK-INTEGER
00000168               SET OPERAND-INSTANCE-NDX TO 1
00000169               PERFORM additionXoperand-num TIMES
00000170                 COMPUTE WORK-INTEGER
00000171                   = WORK-INTEGER +
00000172                     OPERAND-INSTANCE(OPERAND-INSTANCE-NDX)
00000173                 END-COMPUTE
00000174                 SET OPERAND-INSTANCE-NDX UP BY 1
00000175               END-PERFORM
  1. Next, you use a CICS API to get a pointer to the storage that is organized as occurrences of the 01 level data item CALCI01-additionXoperand for the AddOperation language structure in CALCI01.cpy, as shown in Listing 5.
Listing 5. Get container
LINE    ----+-*A-1-B--+----2----+----3----+----4----+----5----+----6----+----7--
00000150      * Get the container whose storage is organized as occurrences
00000151      * of the 01 level data item "CALCI01-additionXoperand"
00000152               EXEC CICS GET CONTAINER(additionXoperand-cont)
00000153                 SET(WORK-DATA-PTR)
00000154                 FLENGTH(WORK-DATA-LEN)
00000155                 RESP(COMMAND-RESP) RESP2(COMMAND-RESP2)
00000156               END-EXEC
00000157               PERFORM CHECK-CONTAINER-COMMAND
  1. Using the linkage section item that you declared previously, establish addressability to each occurrence of the 01 level data item CALCI01-additionXoperand by setting the linkage section item to the address of the container storage, as shown in Listing 6.
Listing 6. Set address
LINE    ----+-*A-1-B--+----2----+----3----+----4----+----5----+----6----+----7--
00000159      * Overlay the contiguous storage of the container with a
00000160      * data structure that allows us to easily access each
00000161      * occurrence of the array.
00000162               SET ADDRESS OF CALCULATOR-OPERAND-OVERLAY
00000163                 TO WORK-DATA-PTR
  1. You can now iterate through each occurrence in the container, as shown in Listing 7. You bind the loop using the additionXoperand-num variable, which indicates the number of occurrences to be found in the container whose name is given in additionXoperand-cont.
Listing 7. Iterate through array occurrences
LINE    ----+-*A-1-B--+----2----+----3----+----4----+----5----+----6----+----7--
00000165      * Loop through array occurrences and compute SUM for
00000166      * "AddOperation".
00000167               INITIALIZE WORK-INTEGER
00000168               SET OPERAND-INSTANCE-NDX TO 1
00000169               PERFORM additionXoperand-num TIMES
00000170                 COMPUTE WORK-INTEGER
00000171                   = WORK-INTEGER +
00000172                     OPERAND-INSTANCE(OPERAND-INSTANCE-NDX)
00000173                 END-COMPUTE
00000174                 SET OPERAND-INSTANCE-NDX UP BY 1
00000175               END-PERFORM
  1. All of the operations in the Calculator Web service are two-way (request-response). Therefore, to complete providing the AddOperation operation, you need to send response data. The section of the template for doing this begins with the comment "Populate Response Language Structure", as shown in Listing 8.
Listing 8. Send response data
LINE    ----+-*A-1-B--+----2----+----3----+----4----+----5----+----6----+----7--
00000239      * -------------------------------------------------------------
00000240      *             Populate Response Language Structure
00000241      * -------------------------------------------------------------
00000242           EVALUATE WS-OPERATION-NAME 
00000243             WHEN OPERATION-NAME-1
  1. The language structure in CALCO01.cpy represents the response data for the AddOperation. Now, simply move the result of the SUM computed while processing the request data into the additionXresult field of the response language structure. The sending of the response is not complete until you PUT a container with the response language structure into the Web service PIPELINE, as shown in Listing 9.
Listing 9. Store addition result
LINE    ----+-*A-1-B--+----2----+----3----+----4----+----5----+----6----+----7--
00000244      * Store addition result into outbound language structure for
00000245      * operation "AddOperation".
00000246               MOVE WORK-INTEGER TO additionXresult
  1. Given that the response language structure is simple in this example, you do not need to PUT additional containers in the PIPELINE for items of variable or unbounded length. The automatically generated PUT of the response language structure is sufficient, and it does not need updating (Listing 10).
Listing 10. Send response language structure
LINE    ----+-*A-1-B--+----2----+----3----+----4----+----5----+----6----+----7--
00000287      * -------------------------------------------------------------
00000288      *               Send Response Language Structure
00000299      * -------------------------------------------------------------
00000300           EVALUATE WS-OPERATION-NAME
00000301             WHEN OPERATION-NAME-1
00000302               EXEC CICS PUT CONTAINER(WS-CONTAINER-NAME)
00000303                 FROM(LANG-CALCO01)
00000304                 RESP(COMMAND-RESP) RESP2(COMMAND-RESP2)
00000305               END-EXEC

The way that you complete the code for the MultiplyOperation and DivideOperation operations is similar to the AddOperation except that the DivideOperation does not need to deal with unbounded arrays. The completed code for the Web service provider is included in the WebServicesforCICSTopDownSample.zip file. To skip the project creation and generation steps, you may import the project interchange file Calculator_Proj.zip, which is included in the .zip file.


Testing the Web service provider

Once the following steps have been completed, you can test the new Web service using the Rational Developer for System z Web Services Explorer (or other means):

  1. Copy the CALCPROV.cbl, CALCI*.cpy, and CALCO*.cpy files to the MVS system.
  2. Compile and link-edit the CALCPROV.cbl Web service provider application into a load dataset within the DFHRPL concatenation of CICS
  3. Define a PROGRAM resource in CICS called CALCPROV and install it.
  4. Copy the CalculatorProvider.wsbind file to a CICS provider-mode PIPELINE pickup directory. If you are using ftp, ensure that the file is transferred in binary mode.
  5. Issue a scan of the provider-mode PIPELINE to install the Web service: CEMT PERFORM PIPELINE(PROVPIPE) SCAN
  6. Ensure that the Web service is "inservice" by issuing CEMT INQUIRE WEBSERVICE(*) and looking for CalculatorProvider.

To test the Web service using the Web service explorer, perform the following steps.

  1. Right-click the Calculator.wsdl file in the /Source directory of the Calculator project in Rational Developer for System z and select Web Services > Test with Web Services Explorer, as shown in Figure 15.
Figure 15. Starting the test
screen capture
  1. Select an operation to test in the displayed tree view on the left, and a corresponding input form will display on the right, as shown in Figure 16. Be sure that the full URI in the WSDL file represents the physical location of the CICS system where the Web service is running.
Figure 16. Select an operation
screen capture
  1. Select an operation to test in the displayed tree view on the left, and a corresponding input form will display on the right, as shown in Figure 16. Be sure that the full URI in the WSDL file represents the physical location of the CICS system where the Web service is running.

Generating Web service requester artifacts using Rational Developer for System z

This article includes a file named WebServicesforCICSTopDownSample.zip. Please extract this file to your C:\ drive before performing the steps in this section (if you have not done so already). In order to be able to execute the example in this section, you will have to have completed the Calculator service provider implementation described in the previous sections.

If the Calculator.wsdl file in the extracted set has not yet been updated, it is critical to do so now. Update the location URI in the CalculatorBinding according to this pattern: http://your.system.ip:cics_tcpipservice_port/cics/services/calculator.

It is now possible to generate the service requester artifacts by following these steps. Where there is no figure, it is because the steps are the same as those in the Generating Web service provider artifacts using Rational Developer for System z section.

  1. In Rational Developer for System z, open the Enterprise Service Tools perspective.
  2. Right-click in the EST Project Explorer and select New > Web Services for CICS project.
  3. Give the project a suitable name (in this example, Calculatorrequester), as shown in Figure 17.
Figure 17. Choose a project name
screen capture
  1. On the next page, specify the Calculator.wsdl file that was included in the .zip file and finish the new project wizard. It is very important that the location URI in the WSDL file is correct at this point, since you will not be allowed to override it in the wizard.
  2. A new project should display in the EST Project Explorer, with the WSDL file located in the Source directory, as shown in Figure 18.
Figure 18. New project
screen capture
  1. Right-click the Calculatorrequester project and select Generate Web Services for CICS Resources.
  2. Specify options on the Launchpad: accept the default Scenario of Create New Service Implementation (top-down) and Conversion type of Interpretive XML Conversion.
  3. Specify the following options on the Application Properties tab of the DFHWS2LS wizard, as shown in Figure 19.
    • Application type: Service Requester
    • Application language: COBOL
    • Program name: CALCRQST
Figure 19. Application Properties options
screen capture
  1. Specify the following option on the Service Properties tab of the DFHWS2LS wizard, as shown in Figure 20.
    • Binding element: CalculatorBinding
Figure 20. Service Properties options
screen capture
  1. Specify the following options on the Structures tab of the DFHWS2LS wizard, as shown in Figure 21.
    • Request file prefix: RCALCI
    • Response file prefix: RCALCO

These options determine the filenames of the generated language structure copybooks. Notice that the copybooks have different filenames than those in the Web service provider in the previous section. This does not occur automatically, but you should do this for clarity.

Figure 21. Structures options
screen capture
  1. Specify the following options on the WSBind tab of the DFHWS2LS wizard, as shown in Figure 22. .
    • WSBIND file name: Calculatorrequester
    • Log file name: Calculatorrequester

These options determine the filenames of the WSBind file and the Log file. You will need to place the WSBind file in the pickup directory of a requester-mode PIPELINE (after you complete the wizard). The Log file provides verbose detail about the internal processing of the Web Services Assistant.

Figure 22. WSBind options
screen capture
  1. Specify the following option on the Template tab of the DFHWS2LS wizard, as shown in Figure 23.
    • Template file name: CALCRQST

This tab allows you to specify the filename of the generated application template. The template is intended to be used as a starting point to develop the new CICS Web service requester application. It contains sample logic for invoking the first operation on the remote Web service.

Figure 23. Template options
screen capture
  1. Click Finish to complete the wizard.

The Calculatorrequester project will be populated with several artifacts. The artifacts in the Targets folder are the generated Web services artifacts that are the basis of the Web service requester implementation.

In this example, six copybooks were generated, as shown in Figure 24. The copybooks suffixed with "I" contain the language structures for the request data of the three operations (addOperation, multiplyOperation, and divideOperation). Those suffixed with "O" contain the respective language structures for the response data. CALCRQST.cbl is the generated template Web service requester template program. The next section will focus on how to complete its logic.

Figure 24. Populated project
screen capture

Implementing a Web service requester using the template

The requester template program CALCRQST.cbl is generated as a complete COBOL application, with areas where the user should fill in the business logic. In the case where the XML Schemas for a given operation (such as AddOperation) contain an unbounded array, additional coding is required to fill in the content of these arrays, because they need to be stored in secondary containers. You will understand more about the secondary containers as the coding unfolds. The following code snippets are taken from the CALCRQST.cbl file provided with this document.

  1. The program begins with some information that identifies it as a CICS web service requester implementation. Again, the logic of this program demonstrates the invocation of the first operation on the remote web service. In this example, you will be calling the AddOperation, as shown in Listing 11.
Listing 11. Calling AddOperation
LINE    ----+-*A-1-B--+----2----+----3----+----4----+----5----+----6----+----7--
00000004      *  *************************************************************
00000005      *             New CICS TS 3.x Web Service Requestor
00000006      *  *************************************************************
00000009       IDENTIFICATION DIVISION.
00000010      *Begin Identification Divsion
00000011        PROGRAM-ID. 'CALCRQST'.
00000012        AUTHOR. WD4Z.
00000013        DATE-WRITTEN. 2/21/07 5:56 PM.
00000014      *End Identification Divsion
  1. The service requester begins with an outbound call, as opposed to consuming a request (as in the provider example). For AddOperation, look inside RCALCI01.cpy, where it is explained that the operands to be summed need to be placed in a container, whose name in turn is to be placed in additionXoperand-cont.

A container is created using the CICS PUT API. Normally, a container is PUT from a storage area in the program. Therefore, declare an area (not in the linkage section) that is organized as occurrences of RCALCI01-additionXoperand such that it can be used to PUT an array of operands, as shown in Listing 12.

Listing 12. Declare a data structure
LINE    ----+-*A-1-B--+----2----+----3----+----4----+----5----+----6----+----7--
00000066      * We declare a data structure to specify each element
00000067      * of the unbounded arrays for the add and multiply operations
00000068      * whose interfaces are represented by the language structures 
00000069      * in RCALCI01.cpy and RCALCI02.cpy which were generated by
00000070      * DFHWS2LS. We use this data structure with the PUT container
00000071      * command.
00000072       1 OPERAND-COUNT PIC 9(9) BINARY.
00000073       1 CALCULATOR-OPERANDS.
00000074           5 OPERAND-INSTANCE OCCURS 0 TO 512 TIMES
00000075             DEPENDING ON OPERAND-COUNT PIC S9(9) COMP-5 SYNC .
00000076
00000077      * For displaying the result on the console
00000078       1 INTEGER-DISP PIC ZZZ,ZZZ,ZZZ,ZZ9.
00000079       1 CONSOLE-TEXT PIC X(80).
  1. When a web service requester or provider is installed in CICS, a WEBSERVICE resource is created. To indicate to CICS which Web service to invoke, specify the name of the WEBSERVICE resource for the requester (not the provider), as shown in Listing 13. In addition, choose to invoke the first operation. Both of the receiving fields in the following code snippet are used with the API, EXEC CICS INVOKE WEBSERVICE.
Listing 13. Specify the Web service
LINE    ----+-*A-1-B--+----2----+----3----+----4----+----5----+----6----+----7--
00000112      * -------------------------------------------------------------
00000113      *      WEBSERVICE resource installed in this CICS region
00000114      * -------------------------------------------------------------
00000115           MOVE 'CalculatorRequestor'
00000116             TO WS-WEBSERVICE-NAME
00000117      * -------------------------------------------------------------
00000118      *        Operation To Invoke On The Remote Web Service
00000119      * -------------------------------------------------------------
00000120           MOVE OPERATION-NAME-1
00000121             TO WS-OPERATION-NAME
  1. The following code segments populate the request language structure and secondary container. On line 125, initialize the primary language structure for the AddOperation request data, as shown in Listing 14.
Listing 14. Populate the request language structure
LINE    ----+-*A-1-B--+----2----+----3----+----4----+----5----+----6----+----7--
00000122      * -------------------------------------------------------------
00000123      *             Populate Request Language Structure
00000124      * -------------------------------------------------------------
00000125           INITIALIZE LANG-RCALCI01
  1. Earlier, you defined a variable-length structure called CALCULATOR-OPERANDS, which is organized exactly like the storage of the secondary container representing the operands to be summed. On lines 129 through 135, the numbers to be summed and their count are stored into CALCULATOR-OPERANDS, as shown in Listing 15.
Listing 15. Specify numbers to be summed
LINE    ----+-*A-1-B--+----2----+----3----+----4----+----5----+----6----+----7--
00000129      * Specify the operands to SUM. Expected SUM is 256.
00000130           MOVE 5  TO OPERAND-COUNT
00000131           MOVE 21 TO OPERAND-INSTANCE(1)
00000132           MOVE 53 TO OPERAND-INSTANCE(2)
00000133           MOVE 87 TO OPERAND-INSTANCE(3)
00000134           MOVE 40 TO OPERAND-INSTANCE(4)
00000135           MOVE 55 TO OPERAND-INSTANCE(5)
  1. On lines 137 through 139, give a name to the secondary container, which contains the operands to be summed, as shown in Listing 16.
Listing 16. Name the secondary container
LINE    ----+-*A-1-B--+----2----+----3----+----4----+----5----+----6----+----7--
00000137      * Specify a container name that will have the operands for the
00000138      * Web service to compute the SUM.
00000139           MOVE 'AddOperands' TO additionXoperand-cont
  1. Line 143 sets the counter for the number of occurrences of RCALCI01-additionXoperand that exist in the secondary container. A container is not self-describing, so it is necessary to tell the consumer of the container the number of instances of the structure ( to which the container is mapped) that are contained within it.

Lines 144 to 148 create the AddOperands container in the current channel from the CALCULATOR-OPERANDS structure in your working storage, as shown in Listing 17. You have now finished populating the request data for the AddOperation operation.

Listing 17. Create the AddOperands container
LINE    ----+-*A-1-B--+----2----+----3----+----4----+----5----+----6----+----7--
00000141      * PUT a container which is organized as occurrences of
00000142      * of RCALCI01-additionXoperand
00000143           MOVE OPERAND-COUNT to additionXoperand-num
00000144           EXEC CICS PUT CONTAINER(additionXoperand-cont)
00000145             CHANNEL(WS-CHANNEL-NAME)
00000146             FROM(CALCULATOR-OPERANDS)
00000147           END-EXEC
00000148           PERFORM CHECK-CONTAINER-COMMAND
Listing 18. Invoke the web service
LINE    ----+-*A-1-B--+----2----+----3----+----4----+----5----+----6----+----7--
00000160      * -------------------------------------------------------------
00000161      *                    Invoke The Web Service
00000162      * -------------------------------------------------------------
00000163           EXEC CICS INVOKE WEBSERVICE(WS-WEBSERVICE-NAME)
00000164             CHANNEL(WS-CHANNEL-NAME)
00000166             OPERATION(WS-OPERATION-NAME)
00000167             RESP(COMMAND-RESP) RESP2(COMMAND-RESP2)
00000168           END-EXEC
00000169           PERFORM CHECK-WEBSERVICE-COMMAND
Listing 19. Retrieve the response
LINE    ----+-*A-1-B--+----2----+----3----+----4----+----5----+----6----+----7--
00000170      * -------------------------------------------------------------
00000171      *             Receive Response Language Structure
00000172      * -------------------------------------------------------------
00000173           EXEC CICS GET CONTAINER(WS-CONTAINER-NAME)
00000174             CHANNEL(WS-CHANNEL-NAME)
00000175             INTO(LANG-RCALCO01)
00000176           END-EXEC
00000177           PERFORM CHECK-CONTAINER-COMMAND
  1. This is reached after the invocation of AddOperation on the remote Web service has completed, and the results have been placed in the additionXresult field of the primary language structure in the RCALCO01.cpy copybook. The logic shown in Listing 18 simply displays the results of the AddOperation invocation to the CICS terminal.
Listing 20. Display the data
LINE    ----+-*A-1-B--+----2----+----3----+----4----+----5----+----6----+----7--
00000000      * COBOL item RCALCO01.cpy/ADDITIONREPLY/additionXresult now
00000000      * holds the result of the call to the web service because
00000000      * of the preceeding INVOKE and GET. The CICS runtime
00000000      * automatically does the data conversion based on the
00000000      * operation name we passed in the INVOKE.
00000000
00000000      * We should now do something with the data, for purposes of this
00000000           MOVE additionXresult TO INTEGER-DISP
00000000           INITIALIZE CONSOLE-TEXT
00000000           STRING
00000000              '<CALCRQST addResult="'
00000000              INTEGER-DISP
00000000              '"></CALCRQST>'
00000000              DELIMITED BY SIZE
00000000              INTO CONSOLE-TEXT
00000000           END-STRING
00000000           EXEC CICS SEND TEXT ERASE
00000000             FROM (CONSOLE-TEXT)
00000000           END-EXEC

The completed code for the Web service requester is included in the Calculatorrequester_Proj.zip, which is available from the download section.

Testing the Web service requester

Once the following steps have been completed, you can test the new Web service requester using the CICS 3270 terminal (or other means):

  1. Copy the CALCRQST.cbl, RCALCI*.cpy, and RCALCO*.cpy to the MVS system.
  2. Compile and link-edit the CALCRQST.cbl Web service requester application into a load dataset within the DFHRPL concatenation of CICS.
  3. Define a PROGRAM resource in CICS called CALCRQST and install it.
  4. Define a transaction called RQST (or anything you’ll remember) and specify CALCRQST as the program that it invokes.
  5. Copy the Calculatorrequester.wsbind file to a CICS requester-mode PIPELINE pickup directory.
  6. Issue a scan of the requester-mode PIPELINE to install the Web service: CEMT PERFORM PIPELINE(REQPIPE) SCAN
  7. Ensure that the Web service requester and provider are "inservice" by issuing CEMT INQUIRE WEBSERVICE(*), and look for Calculatorrequester and CalculatorProvider.

The results should look like that shown in Figure 25.

Figure 25. Results showing both CalculatorProvider and Calculatorrequester
screen capture

To test the Web service requester, log into the CICS terminal and invoke the RQST transaction (Figure 26), which will execute the CALCRQST.cbl application. Recall that the Web service requester application invokes the AddOperation operation on the CalculatorProvider WEBSERVICE. The values to be summed are hard-coded in the service requester program, and should equal 256.

Figure 26. The RQST transaction
screen capture

Figure 27 shows a successful end-to-end test of requester to provider.

Figure 27. CALCRQST addResult is 256
screen capture

What you have learned

Using Rational Developer for System z, you have developed two types of new applications: a Web service provider and a Web service requester. This article also showed you the improved usability of DFHWS2LS: a graphical interface and a template to help you generate provider and requestor programs.


Downloads

DescriptionNameSize
Code sampleCalculator_Proj.zip30KB
Code sampleCalculatorRequestor_Proj.zip30KB

Resources

Learn

Get products and technologies

Discuss

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 Rational software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Rational, WebSphere, DevOps
ArticleID=297470
ArticleTitle=Implement a Web service provider and requester using native CICS APIs and IBM Rational Developer for System z
publish-date=04012008