Introduction

In On Demand Business, enterprise-level applications need to integrate with services provided by other applications both inside and outside the enterprise. Building such composite applications using service-oriented principles requires an agile business process execution environment and legacy support for service-oriented computing. In this paper, we illustrate how to use the new SOAP for CICS feature offered by the CICS TS to integrate legacy applications with the business processes running in IBM® WebSphere® Business Integration Server Foundation.

In Part 1 of this series we introduced an on demand business process scenario for an Order to Manufacturing Processing System (OTMPS). This paper describes how to integrate a legacy CICS service with the OTMPS process. We used a CICS service that validates the input orders to check that they contain an allowable combination of features. For example, the service validates the storage requirement in the context of available physical racks in the system. This service receives an order number and associated configuration properties (or features), validates the order, and returns messages indicating the results of the validation process.

The required software on the CICS server includes:

• CICS TS 2.3 with SOAP for CICS feature installed. The CICS SOAP implementation uses CICS Business Transaction Services (BTS). The SOAP HTTP transport uses CICS Web Support. (Note: We use CICS TS 2.3 as the base in this paper. As of this writing, CICS TS 3.1 has been released with Web services capabilities over and above those provided by CICS TS 2.3. See the Resources section for information about the latest features available with CICS TS 3.1.)
• CICS BTS processes are used to support the SOAP handler pipelines. BTS is a component of CICS TS.
• Enterprise Cobol V3 or Enterprise PL/I V3.

Back to top

Architecture

There are a number of architectural choices available to connect an on demand application client to CICS transactions including the SOAP for CICS feature, J2EE Connector Architecture (JCA), and Enterprise Java Beans. The architecture presented in this scenario uses the SOAP for CICS feature and is illustrated in Figure 1.

The major components at the service provider side of this architecture are as follows:

• Service provider transport
• SOAP Envelope parser
• SOAP envelope builder
• Message adapter

CICS provides the first three components; the user supplies the message adapter component. As Figure 1 shows, these components provide two important functions: 1) pipeline message processing and 2) message adaptation to business logic. The pipeline processing helps the CICS service provider parse incoming messages and extract the necessary parts needed for processing. For example, in an incoming message scenario, the service provider transport extracts the SOAP message from the transport protocol (for example, HTTP headers) and passes the SOAP message to the next processor in the pipeline. The SOAP envelope parser strips off the SOAP envelope and passes the XML body to the message adapter. In the case of the outgoing message scenario, the pipeline processing adds the message headers and necessary transport headers to the outgoing XML message. It is possible to add additional pipeline processors to the pipeline chain for extended capabilities such as security, logging, and reliability. The message adapter adds the business logic to map the incoming XML message to the COMMAREA and invokes the correct business logic in local or remote CICS regions.

The client-side architecture illustrates proxies that can emit SOAP messages with the XML message body required for executing the business logic in CICS. The proxies are responsible for pushing the messages onto the appropriate transport communication protocol (for example, HTTP, HTTPS, and MQ). In addition, the proxy provides helpers to extract the messages from CICS.

Back to top

Scenario overview

In the OTMPS scenario, after receiving a new customer order from a sales office, its configuration must be validated before it is sent to the manufacturing floor to be built. The CICS Web service validates orders to check that they contain a valid combination of features. As input it takes an order number and associated configuration parameters (or features). The called service tests the order to see if it is valid. The output response includes a return code that indicates success or failure and an array of messages indicating the results of processing.

The application is currently implemented as a CICS transaction accessed through a 3270 Interactive System Productivity Facility (ISPF) front-end. The CICS transaction program (the business logic) receives 3270 input through a COMMAREA and sends back 3270 output through another COMMAREA. The business logic program is written in COBOL. Listing 1 and Listing 2 show the existing input and output COMMAREA respectively.

				
INCOMMAREA.     
03 REQ-TYPE                PIC X(8) .
03 ORDERNO                 PIC X(10) .
03 FEATURE-ARRAY OCCURS 150 TIMES.
             05 FEATURE               PIC X(10). 
             05 QUANTITY              PIC X(3).

				
01   OUTCOMMAREA.  
    03 RETURNCODE          PIC X(3).   
    03 VALIDATION-RESULTS-ARRAY   OCCURS 100 TIMES.
             05 MSG-PREFIX           PIC X(3).  
             05 MSG-TEXT             PIC X(80). 

Back to top

Service provider side

The following section illustrates the components developed for the service provider side. In this section we discuss the user-defined modules needed for service-side processing. As indicated in the architecture section, there are two types of user-supplied components at the service provider side: 1) pipeline header processor and 2) message adapter. In this section we illustrate how to develop the message adapter component.

Create the message adapter

A message adapter performs functions needed to translate between the SOAP XML format used by the WebSphere Process Choreographer client and the copybook COMMAREA format used by the business logic CICS transaction.

As illustrated in Figure 1, the input to the message adapter program comes from the CICS pipeline container. The last stage in the inbound pipeline is the message adapter. By this time all SOAP headers have been processed and removed, leaving just the XML payload needed for the business logic.

You can create the message adapter in several ways, including the following:

• WebSphere Studio Enterprise Developer (Enterprise Developer) provides a tool to generate message adapters from COBOL copybooks (see Resources for information about Enterprise Developer and its use with SOAP/CICS). In addition to generating the message adapter, Enterprise Developer can also generate an XML schema to represent the input and output copybook COMMAREAs.
• Message adapters can also be developed using the SAX (Simple API for XML) parsing function built into Enterprise COBOL V3 and Enterprise PL/I V3.
• In CICS TS V3.1, the CICS Web Services Assistant provides support to automatically convert between XML and COBOL, C, C++, or PL/I structures (see Resources for information about the latest features available with CICS TS 3.1.).

The message adapter performs three major functions:

• Convert the inbound XML request to the input COMMAREA format.
• Link to the existing business logic program.
• Convert the output COMMAREA to an outbound XML response.

Convert the XML request to input COMMAREA format

Listing 3 shows the working storage area and linkage section.

				
       WORKING-STORAGE SECTION.                                         
       01 WS-START.                                                     
         03 BOD-PTR                  USAGE IS POINTER.                  
         03 BOD-LEN                  PIC S9(8) COMP-4.   
         03 GETMAIN-PTR              USAGE IS POINTER.                  
         03 GETMAIN-LEN              PIC S9(8) COMP-4.                  
      * Container names used by BTS Activity                            
         03 PIPE-INPUT               PIC X(16) VALUE 'INPUT'.           
         03 PIPE-OUTPUT              PIC X(16) VALUE 'OUTPUT'.                        

      * Externally referenced data areas                                
       LINKAGE SECTION.                                                 
       01 BOD-AREA.                                                     
          02 FILLER                  PIC X OCCURS 320000                
                                           DEPENDING ON BOD-LEN.        
       01 GETMAIN-AREA.                                                 
          02 FILLER                  PIC X OCCURS 320000                
                                           DEPENDING ON GETMAIN-LEN.

The message adapter determines the size of the incoming pipeline container, allocates storage for it, and moves its contents into working storage. These functions are shown in steps 1 through 3 below.

1. Get the SOAP document body from the input pipe.

   EXEC CICS GET CONTAINER(PIPE-INPUT) SET(BOD-PTR) FLENGTH(BOD-LEN) END-EXEC.

   
   
   
   
2. Copy the input container to GETMAIN storage, since the SET pointer is volatile.

   IF BOD-LEN > 0 SET ADDRESS OF BOD-AREA TO BOD-PTR MOVE BOD-LEN TO GETMAIN-LEN EXEC CICS GETMAIN SET(GETMAIN-PTR) FLENGTH(GETMAIN-LEN) END-EXEC SET ADDRESS OF GETMAIN-AREA TO GETMAIN-PTR MOVE BOD-AREA TO GETMAIN-AREA SET BOD-PTR TO GETMAIN-PTR SET ADDRESS OF BOD-AREA TO BOD-PTR END-IF.

   
   
   
   
3. Use the COBOL built-in functions to parse the XML and convert it to the input copybook COMMAREA format. This step instantiates an XML parser (Listing 4) and executes a call back function (Listing 5).

				
XML PARSE BOD-AREA PROCESSING PROCEDURE XML-HANDLER          
 END-XML.  

				
     XML-HANDLER SECTION.                                             
           EVALUATE XML-EVENT                                           
              WHEN 'START-OF-ELEMENT'                                   
                 MOVE XML-TEXT TO CURRENT-ELEMENT                       
              WHEN 'CONTENT-CHARACTERS'                                 
                 EVALUATE CURRENT-ELEMENT                               
                  WHEN 'Type'                                        
                    MOVE XML-TEXT TO REQ-TYPE OF INCOMMAREA                     
* All the other request XML elements would follow here (in other words, 
order number, feature array).                           
                 END-EVALUATE                                           
           END-EVALUATE.                                                
       XML-HANDLER-END. EXIT.        

Link to the existing business logic program

Our sample scenario is executing the ORDVLDT business logic program in CICS as shown in Listing 6. We're passing in the COMMAREA we built above in the XML parsing routine.

				
EXEC CICS LINK PROGRAM('ORDVLDT') COMMAREA(INCOMMAREA)
END-EXEC  

Convert output COMMAREA to XML SOAP response

The CICS message adapter program builds a text string to represent the XML response document. The outbound stages of the CICS pipeline will then wrap this document in the proper SOAP headers.

The SOAP response message from CICS must include the correct namespace URI for the response message. Without the namespace information specifying the response format (see Resources for details on SOAP specification), the client proxy code will not be able to unmarshall the response into the correct Java objects.

For example, in order to use the namespace http://www.coats.com/schemas/ValidateOrderOInterface for the Response element, follow these steps:

Step 1: Define the return message as shown in Listing 7 to send back to the client in a container.

				
     * Data items used to build a response message  
     01  ORD-MESSAGE -FIRST.                                                   
        03 FILLER              PIC X(15) VALUE '<SOAP-ENV:Body>'.       
        03 FILLER              PIC X(21) VALUE '<om:ValidateOrderResp'.       
        03 FILLER              PIC X(22) VALUE ' xmlns:om="http://www.'. 
        03 FILLER              PIC X(18) VALUE 'coats.com/schemas/'. 
        03 FILLER              PIC X(26) VALUE 'ValidateOrderOInterface ">'.
        03 FILLER              PIC X(12) VALUE '<ReturnCode>'.         
        03 RTNCODE        PIC X(3)  VALUE SPACES.                   
        03 FILLER              PIC X(13) VALUE '</ReturnCode>'.            
        03 FILLER              PIC X(10) VALUE '<Messages>'.         
        03 ORD-MESSAGE -FIRST-LEN       PIC S9(8) COMP-4 VALUE 140.              
                                                                        
      *                                                                 
       01  ORD-MESSAGE -DETAIL.                                                  
        03 FILLER             PIC X(14) VALUE '<OrderMessage>'.          
        03 FILLER             PIC X(15) VALUE '<MessagePrefix>'.          
        03 PREFIX            PIC X(3)  VALUE SPACES.                   
        03 FILLER             PIC X(16) VALUE '</MessagePrefix>'.          
        03 FILLER             PIC X(13) VALUE '<MessageText>'.          
        03 TEXT                PIC X(80)  VALUE SPACES.                   
        03 FILLER             PIC X(14) VALUE '</MessageText>'.          
        03 FILLER             PIC X(15) VALUE '</OrderMessage>'.         
        03 ORD-MESSAGE -DETAIL-LEN     PIC S9(8) COMP-4 VALUE 170.               
                                                                        
      *                                                                 
       01  ORD-MESSAGE -LAST.                                                    
        03 FILLER              PIC X(11) VALUE '</Messages>'.      
        03 FILLER              PIC X(23) VALUE '</om:ValidateOrderResp>'.      
        03 FILLER              PIC X(16) VALUE '</SOAP-ENV:Body>'.      
        03 ORD-MESSAGE -LAST-LEN        PIC S9(8) COMP-4 VALUE 50.   

Step 2: Build the output XML document from the output COMMAREA of the business logic program. When control is returned from the linked business logic program (ORDVLDT) back to the message adapter, take the output COMMAREA as shown in Listing 8 and build the output XML document from it (as shown in ORD-MESSAGE-DETAIL in Listing 7).

				
01   OUTCOMMAREA.  
    03 RETURNCODE          PIC X(3).   
    03 VALIDATION-RESULTS-ARRAY   OCCURS 100 TIMES.
             05 MSG-PREFIX           PIC X(3).  
             05 MSG-TEXT               PIC X(80).

We write out the XML document header data (ORD-MESSAGE-FIRST structure) to the output XML message as shown in Listing 9.

				
01 OUT-MSG-VCHAR.                                                
03 OUT-MSG-LEN              PIC S9(8) COMP-5 VALUE ZERO.       
03 OUT-MSG.                                                    
04 FILLER                PIC X OCCURS 4092                  
                                           DEPENDING ON OUT-MSG-LEN.    
MOVE ORD-MESSAGE--FIRST(1 : ORD-MESSAGE--FIRST-LEN) TO OUT-MSG(1 : ORD-
MESSAGE--FIRST-LEN)                           
ADD ORD-MESSAGE--FIRST-LEN TO OUT-MSG-LEN                          

We then loop through the VALIDATION-RESULTS array (see the sidebar CICS 32K COMMAREA size restriction and workaround for details). For each element in the OUTCOMMAREA VALIDATION-RESULTS array, we concatenate an ORD-MESSAGE-DETAIL structure to the output XML message:

OUTCOMMAREA. MSG-PREFIX(INDEX) -> ORD-MESSAGE-DETAIL.PREFIX
OUTCOMMAREA. MSG-TEXT(INDEX) -> ORD-MESSAGE-DETAIL.TEXT

After all the VALIDATION-RESULTS array elements have been processed, we write the XML document trailer data (ORD-MESSAGE-LAST structure) to the output XML message, place the XML document in the CICS pipeline output container, and exit from the message adapter program (shown in Listing 10).

				
MOVE ORD-MESSAGE-LAST(1 : ORD-MESSAGE-LAST-LEN) TO OUT-MSG(1 + OUT-MSG-LEN : ORD-
MESSAGE-LAST-LEN)
ADD ORD-MESSAGE-LAST-LEN TO OUT-MSG-LEN

EXEC CICS PUT CONTAINER(PIPE-OUTPUT)
FROM(OUT-MSG)                                           
                FLENGTH(OUT-MSG-LEN)                                    
END-EXEC.                                                    

EXEC CICS RETURN                                             
END-EXEC.                                            
MAIN-PROCESSING-END. 
EXIT.

Back to top

Conclusion

This paper illustrated an architectural overview and step-by-step methods for developing message adapters in CICS TS for XML to COMMAREA conversion. The authors showed you how to develop service-provider-side artifacts in CICS v2.3 TS including creating message adapters, executing CICS programs, and enabling large data transfers between CICS applications. CICS TS V3.1 provides capabilities including channels and containers for optimized data handling rather than the COMMAREA. Part 11 of this series will illustrate how to integrate CICS with the workflows using various tools including WebSphere Studio Enterprise Developer, and WebSphere Studio Application Develper - Integration Edition.

Back to top

Download

Information about download methods

Resources

• Get your hands on application development tools and middleware products from DB2®, Lotus®, Rational®, Tivoli®, and WebSphere®. You can download evaluation versions of the products at no charge, or select the Linux® or Windows® version of developerWorks' Software Evaluation Kit.
  
  
• Extend and integrate your existing IT assets using WebSphere Studio Application Developer - Integration Edition, a next generation IDE, and deploy them to WebSphere Business Integration - Server Foundation.
  
  
• Use WebSphere Studio Enterprise Developer to enable your CICS application as a Web services provider with "XML and Web Services for the Enterprise: Providing XML and Web Services Interface To a CICS Application".
  
  
• Learn about enabling CICS for the Internet with "Architecting e-business Access to CICS Update".
  
  
• Download the SOAP for CICS: User's Guide (SC34-6315) from the IBM Publications Center.
  
  
• For more information about SOAP, read the SOAP World Wide Web Consortium SOAP specification.
  
  
• Browse the WebSphere Application Developer - Integration Edition InfoCenter.
  
  
• Explore the enhanced features available with CICS TS V3.1.
  
  
• Browse for books on these and other technical topics.
  
  
• Get involved in the developerWorks community by participating in developerWorks blogs.
  
  
• Want more? The developerWorks SOA and Web services zone hosts hundreds of informative articles and introductory, intermediate, and advanced tutorials on how to develop Web services applications.
  
  

About the authors

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• Architecture
• Scenario overview
• Service provider side
• Conclusion
• Download
• Resources
• About the authors
• Comments

Next steps from IBM

Rational Tester for SOA Quality is an automated web services testing and SOA testing tool that supports Web services SOAP, HTTP(S), JMS, WS-Security, UDDI, and RESTful standards.

---

• Try: The no-charge Rational Service Tester for SOA Quality helps quality assurance professionals validate web service based SOA application..
• Article: See the whats new with Rational Service Tester for SOA Quality, and its Generic Service Client, which provides a single client to interact with any SOA service type.
• Tutorial: Get hands-on experience with this Transport for SOAP feature tutorial using Rational Tester for SOA Quality.
• Buy: Rational Service Tester for SOA Quality

My developerWorks community

Dig deeper into SOA and Web services on developerWorks

Calling all developers

Download no charge Lotus Domino Designer

Special offers