Web services have opened opportunities to integrate the applications at an enterprise level irrespective of the technology they have been implemented in. IBM's CICS transaction server for z/OS v3.1 can support web services. It can help expose existing applications as web services or develop new functionality to invoke web services.

One of the commonly used protocols for CICS web services is SOAP for CICS. It enables the communication of applications through XML. It supports as a service provider and service consumer independent of platform and language. SOAP for CICS enables CICS applications to be integrated with the enterprise via web services as part of lowering the cost of integration and retaining the value of the legacy application. SOAP for CICS also comes along with the implementation encoder and decoder. This article describes two cases where CICS acts as a service provider and also as a consumer for complex datatype objects. CICS SOAP 1.2 is the SOAP implementation and encoding and decoding is done by the PIPELINE programs. Two exclusive PIPELINEs need to be defined, one for the provider and the other for the consumer.

IBM provides CICS Web Services Assistants, namely, DFHLS2WS and DFHWS2LS. The DFHLS2WS utility takes a language data structure used by the service provider and generates the WSDL and WSBIND files. The WSBIND file is used at runtime to convert a SOAP body to a language data structure and vice-a-versa. The DFHWS2LS takes the WSDL provided by a service and generates the language data structure and a WSBIND file. Complex data types are handled by these utilities. The languages supported by these utilities include COBOL, Java, C++, and PL1. The web services are registered in the CICS region using the PIPELINE SCAN command (see Figure 1).

CICS as a Service Consumer - Handling Multiple Result Sets
The application is a Flight Inquiry. The input screen has the Departure and Arrival cities along with the departure date. This invokes a Java web service, which does a query on an Oracle database to retrieve all the flights between the cities on that date. The result is a varying list of flights between different city pairs.

The high-level steps followed in the coding are:

1. Received the WSDL file for the service to be consumed. Appendix A has the WSDL.
2. Used the Web services assistant, DFHWS2LS, to create the request and response copybooks using the WSDL. Set the PGMINT parameter to CHANNEL as we do not know the size of the data being returned. This will help overcome the COMMAREA size limitations in case we receive a huge amount of data. Appendix B has these copybooks.
3. Did a PIPELINE SCAN on the pipeline, which has been defined to be used when the CICS is a web service consumer.
4. Coded a program to capture inputs and pass them to a wrapper that invokes the web service and creates a TSQ containing the response received. Display program reads the TSQ and displays data.

Figure 2 is the input screen shot of the sample application.

Extracting values from the result sets received is a little tricky. The first GET CONTAINER gives us the number of result sets received; two in the example below and the name of a container, which further contains container names of the result sets. The next GET CONTAINER gets us all the container names, which store the actual values. Then we loop through these container name and value pairs to get finally to the data to be displayed.

The first GET CONTAINER gets the name of the container which has container names containing the data:

EXEC CICS GET CONTAINER
CONTAINER (‘DFHWS-DATA      ‘)
CHANNEL (‘FLTDTLS-CHANEL  ‘)
INTO (‘....DFHPI00000000000')
FLENGTH (20)
NOHANDLE

The above result in HEX:

EXEC CICS GET CONTAINER
CONTAINER (X'C4C6C8E6E260C4C1E3C1404040404040')
CHANNEL (X'C6D3E3C4E3D3E260C3C8C1D5C5D34040')
INTO (X'00000002C4C6C8D7C9F0F0F0F0F0F0F0F0F0F0F0') 2 total result sets received
FLENGTH (X'00000014')
NOHANDLE

The second GET CONTAINER gets all the container names containing actual data. There is no demarcation between result sets. The container names are just a bunch of sequenced names.

EXEC CICS GET CONTAINER
CONTAINER (‘DFHPI00000000000')
CHANNEL (‘FLTDTLS-CHANEL  ‘)
INTO (‘....DFHPI00000000001.... DFHPI00000000002.... DFHPI00000000003....'...)
FLENGTH (360)
NOHANDLE

The above maps to the complete XML output as shown below. Each of the DFHPI* is the container name of the actual data element, e.g., <airways>, <arrivalDate>, <capacity>, etc., in the file

We then loop through  the GET CONTAINERS to get actual data. In our case, each result set contains nine elements (airways, arrivalDate, capacity, departureDate, flightFrom, flightNo, flightTo, flightTravelCode and price, refer to the XML output, between <return> </return>). Hence one loop goes through nine GET CONTAINERS.

EXEC CICS GET CONTAINER
CONTAINER (‘DFHPI00000000001')
CHANNEL (‘FLTDTLS-CHANEL  ‘)
INTO (‘SPICE'...)
FLENGTH (255)
NOHANDLE

The above maps to the XML output of <airways>SPICE</airways>

EXEC CICS GET CONTAINER
CONTAINER (‘DFHPI00000000002')
CHANNEL (‘FLTDTLS-CHANEL  ‘)
INTO (‘2008-06-28T19:45:00+05:30')
FLENGTH (32)
NOHANDLE

The above maps to the XML output  <arrivalDate>2008-06-28T19:45:00+05:30</arrivalDate> and so on and so forth till end of data.

This way of using complex datatype objects of an advanced Java application can be used by a legacy system as a consumer of service will have a greater advantage of leveraging the concept of web services for legacy systems.

Listing 1 is the XML output from the SOAPSonar web-services testing tool with the inputs mentioned in Figure 2. Please note that this is just to understand the output structure. When the communication happens directly between the provider and the consumer, we do not see this output.

Figure 3 is the output screenshot of the sample application.

CICS as a Service Provider - Creation of an Order ID
The application stores order details in a DB2 database on the mainframe and creates an order ID for the orders received through the external application(s). This service on the z/OS mainframe is tested through a Java application in the Windows environment. The result is an Order ID (unique number) of the order been placed.

The high-level steps followed in the coding are:

1. Created the language structure (COBOL request copybook) for the service to be developed.
2. Used the web services assistant, DFHLS2WS, to create the WSDL. Used the PGMINT =COMMAREA. Appendix C has the copybook.
   
3. Scanned the inbound pipeline, which has been defined to be used when the CICS is a web service provider.
   
4. Coded a program to receive input from the service consumer, inserts the order details and a unique order ID in the database, and returns the order UD to the service consumer.

The following are the steps involved in the web service testing. Rows from the DB2 table ORDER_DETAIL:

---------+---------+---------+--SELECT * FROM UCHB002.ORDER_DETAIL;
---------+---------+---------+--
ORDER_ID  PRODUCT_CODE  PRODUCT_DESC  PRODUCT_PRICE  PRODUCT_QTY
---------+---------+---------+--
DSNE610I NUMBER OF ROWS DISPLAYED IS 0
DSNE616I STATEMENT EXECUTION WAS SUCCESSFUL, SQLCODE IS 100
---------+---------+---------+--

The XML output from the SOAPSonar web services testing tool with the above inputs (see Figure 4). Please note that this is just to understand the output structure when the communication happens directly between the provider and the consumer (see Figure 5).

Rows in the DB2 table ORDER_DETAIL:

---------+---------+---------+---------
SELECT * FROM UCHB002.ORDER_DETAIL;
---------+---------+---------+---------
ORDER_ID  PRODUCT_CODE  PRODUCT_DESC   PRODUCT_PRICE  PRODUCT_QTY
---------+---------+---------+---------
1  Soap    Dove      55.00     10
1  Oil     SunFlower 99.00      2
DSNE610I NUMBER OF ROWS DISPLAYED IS 2
DSNE616I STATEMENT EXECUTION WAS SUCCESSFUL, SQLCODE IS 100
---------+---------+---------+---------

Conclusion
With the increasing demand for integration of enterprise applications with complex data type structures that have an advantage for manipulating large and complex data, developers have looked at various options one of which is web services. In this article, we have developed a CICS-based program to act as web service provider and consumer using complex data types.

References

• http://www.redbooks.ibm.com/abstracts/sg247126.html
• http://www-306.ibm.com/software/htp/cics/soap/
• http://webservices.sys-con.com/read/39850.htm
• http://publib.boulder.ibm.com/infocenter/idshelp/v10/index. jsp?topic=/com.ibm.ddi.doc/ddi168.htm
• http://www.onjava.com/pub/a/onjava/excerpt/jsoap_5/index1.html