Welcome!

Microservices Expo Authors: Zakia Bouachraoui, Elizabeth White, Pat Romanski, Liz McMillan, Yeshim Deniz

Related Topics: Microservices Expo

Microservices Expo: Article

Developing a CICS-Based Web Service

CICS as a service provider and consumer

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

More Stories By GVB Subrahmanyam

GVB Subrahmanyam an Application Developer, Lead, Project Manager, Development Manager and Delivery Manager in a wide variety of business applications as part of an IT service provider. He focuses on Development, Delivery and Sustenance of IT Applications in Supply Chain/Insurance/Banking/Finance. Albeit most of his projects are Java-based assignments, he is technology agnostic.

In his current role, Subrahmanyam is working as a solution provider for Commercial Healthcare, Insurance, banking and Financial systems with Mahindra Satyam. He is also TOGAF certified Enterprise Architect and IBM certified Ratioanal Software Architect.

GVB Subrahmanyam has an M.Tech. and Ph.D. from IIT Kharagpur in the area of Chemical Technology, India and MS in Software Systems from BITS Pilani. He is also a PMI certified PMP. He attended one year of the Executive Program in Business Management(EPBM) from IIM Calcutta.

More Stories By Sree Kusumanchi

Sree Kusumanchi is lead architect with the Legacy Transformation Group in Satyam Computer Services and has a masters in technology from BITS Pilani.

More Stories By Girish Mokhasi

Girish Mokhasi is technical architect for Legacy Transformation Group in Satyam Computer Services.

Comments (0)

Share your thoughts on this story.

Add your comment
You must be signed in to add a comment. Sign-in | Register

In accordance with our Comment Policy, we encourage comments that are on topic, relevant and to-the-point. We will remove comments that include profanity, personal attacks, racial slurs, threats of violence, or other inappropriate material that violates our Terms and Conditions, and will block users who make repeated violations. We ask all readers to expect diversity of opinion and to treat one another with dignity and respect.


Microservices Articles
When building large, cloud-based applications that operate at a high scale, it’s important to maintain a high availability and resilience to failures. In order to do that, you must be tolerant of failures, even in light of failures in other areas of your application. “Fly two mistakes high” is an old adage in the radio control airplane hobby. It means, fly high enough so that if you make a mistake, you can continue flying with room to still make mistakes. In his session at 18th Cloud Expo, Lee A...
In his general session at 19th Cloud Expo, Manish Dixit, VP of Product and Engineering at Dice, discussed how Dice leverages data insights and tools to help both tech professionals and recruiters better understand how skills relate to each other and which skills are in high demand using interactive visualizations and salary indicator tools to maximize earning potential. Manish Dixit is VP of Product and Engineering at Dice. As the leader of the Product, Engineering and Data Sciences team at D...
Lori MacVittie is a subject matter expert on emerging technology responsible for outbound evangelism across F5's entire product suite. MacVittie has extensive development and technical architecture experience in both high-tech and enterprise organizations, in addition to network and systems administration expertise. Prior to joining F5, MacVittie was an award-winning technology editor at Network Computing Magazine where she evaluated and tested application-focused technologies including app secu...
Containers and Kubernetes allow for code portability across on-premise VMs, bare metal, or multiple cloud provider environments. Yet, despite this portability promise, developers may include configuration and application definitions that constrain or even eliminate application portability. In this session we'll describe best practices for "configuration as code" in a Kubernetes environment. We will demonstrate how a properly constructed containerized app can be deployed to both Amazon and Azure ...
Modern software design has fundamentally changed how we manage applications, causing many to turn to containers as the new virtual machine for resource management. As container adoption grows beyond stateless applications to stateful workloads, the need for persistent storage is foundational - something customers routinely cite as a top pain point. In his session at @DevOpsSummit at 21st Cloud Expo, Bill Borsari, Head of Systems Engineering at Datera, explored how organizations can reap the bene...
Using new techniques of information modeling, indexing, and processing, new cloud-based systems can support cloud-based workloads previously not possible for high-throughput insurance, banking, and case-based applications. In his session at 18th Cloud Expo, John Newton, CTO, Founder and Chairman of Alfresco, described how to scale cloud-based content management repositories to store, manage, and retrieve billions of documents and related information with fast and linear scalability. He addresse...
The now mainstream platform changes stemming from the first Internet boom brought many changes but didn’t really change the basic relationship between servers and the applications running on them. In fact, that was sort of the point. In his session at 18th Cloud Expo, Gordon Haff, senior cloud strategy marketing and evangelism manager at Red Hat, will discuss how today’s workloads require a new model and a new platform for development and execution. The platform must handle a wide range of rec...
SYS-CON Events announced today that DatacenterDynamics has been named “Media Sponsor” of SYS-CON's 18th International Cloud Expo, which will take place on June 7–9, 2016, at the Javits Center in New York City, NY. DatacenterDynamics is a brand of DCD Group, a global B2B media and publishing company that develops products to help senior professionals in the world's most ICT dependent organizations make risk-based infrastructure and capacity decisions.
Discussions of cloud computing have evolved in recent years from a focus on specific types of cloud, to a world of hybrid cloud, and to a world dominated by the APIs that make today's multi-cloud environments and hybrid clouds possible. In this Power Panel at 17th Cloud Expo, moderated by Conference Chair Roger Strukhoff, panelists addressed the importance of customers being able to use the specific technologies they need, through environments and ecosystems that expose their APIs to make true ...
In his keynote at 19th Cloud Expo, Sheng Liang, co-founder and CEO of Rancher Labs, discussed the technological advances and new business opportunities created by the rapid adoption of containers. With the success of Amazon Web Services (AWS) and various open source technologies used to build private clouds, cloud computing has become an essential component of IT strategy. However, users continue to face challenges in implementing clouds, as older technologies evolve and newer ones like Docker c...