®

IBM Software Group

Creating and Calling CICS Web Services

Jon Sayles, IBM Software Group, Rational EcoSystems Team

© 2009 IBM Corporation

IBM Trademarks and Copyrights

 © Copyright IBM Corporation 2007, 2008, 2009. All rights reserved.

 The information contained in these materials is provided for informational purposes

only, and is provided AS IS without warranty of any kind, express or implied. IBM
shall not be responsible for any damages arising out of the use of, or otherwise
related to, these materials. Nothing contained in these materials is intended to, nor
shall have the effect of, creating any warranties or representations from IBM or its
suppliers or licensors, or altering the terms and conditions of the applicable license
agreement governing the use of IBM software. References in these materials to IBM
products, programs, or services do not imply that they will be available in all countries
in which IBM operates.
 This information is based on current IBM product plans and strategy, which are
subject to change by IBM without notice. Product release dates and/or capabilities
referenced in these materials may change at any time at IBM’s sole discretion based
on market opportunities or other factors, and are not intended to be a commitment to
future product or feature availability in any way.
 IBM, the IBM logo, the on-demand business logo, Rational, the Rational logo, and
other IBM Rational products and services are trademarks or registered trademarks of
the International Business Machines Corporation, in the United States, other
countries or both. Other company, product, or service names may be trademarks or
service marks of others.

2
Course Contributing Authors
 Thanks to the following individuals, for assisting with this course:
 David Myers/IBM
 Bill Klein
 Reginaldo Barosa
 Mike Wrzinski/Sentry Insurance

3
Purpose of This Document
 Course Name: COBOL Foundation Training - with RDz

 Course Description: Learn the COBOL language, RDz and learn z/OS terms, concepts and development skills in this course.

 Pre-requisites: Some experience in a 3rd or 4th Generation Language is expected. SQL is also recommended.

 Course Length: 10 days

 Topics (Agenda) for the COBOL Course

 Getting Started - installing and configuring RDz - and the course materials, and using Eclipse to edit COBOL
 COBOL General Language Rules
 Basic COBOL Statements
 Data records and table handling
 Debugging Programs - Note: Deep dive on using RDz for common COBOL programming errors (001, 0C4, 0C7, infinite loops, fall-thru, etc.)
 Input/Output and Report Writing Patterns
 Sequential File Match/Merge Patterns
 COBOL Subprograms and the Linkage Section
 Structured Programming Concepts and Coding Patterns
 Advanced Character Manipulation, COBOL Intrinsic Functions, Date and Time coding patterns, and Language Environment calls
 z/OS Concepts and JCL
 Compile/Link & Run Procs on the mainframe
 Indexed file Coding Patterns
 Sort/Merge and Master File Update Coding Patterns
 Accessing DB2 Data and Stored Procedures
 COBOL in the Real World:
– CICS - lecture only
– IMS (DL/I and TM) – lecture only
– Batch processing – access the IBM mainframe
– Java calling COBOL
– COBOL and XML Statements
– SOA and COBOL - creating and calling Web Services
– Web 2.0 using Rich UI
4
Course Details
 Audience
 This course is designed for application developers who have learned or
programmed in a 3rd or 4th generation language – and who need to build leading-
edge applications using COBOL and Rational Developer for System z.

 Prerequisites
 This course assumes that the student has a basic understanding and knowledge
of software computing technologies, and general data processing terms,
concepts and vocabulary.
 Knowledge of SQL (Structured Query Language) is assumed for database
access is assumed as well.
 Basic PC and mouse-driven development skills, terms and concepts are also
assumed.
 Note that we will be covering RDz's mainframe-editor-compliant function key idiom in
this unit

5
Unit
RDz and Services
(SOA)
Topics:
 XML and Web Services Terms and Concepts
 RDz and Web Services
 Setting up for Web Services
 Creating and consuming an RDz Web Service
 Consuming a 3rd Party Web Service

6
Topic objectives
After completing this topic, you should be able to:
Describe the foundation SOA terms and vocabulary:
 Service
 Service Oriented Architecture
 Web Service
Describe the role CICS can play, in a Service Oriented Architecture
Define the purpose of XML
Differentiate between:
 Service
 WSDL
 XML
 SOAP
Describe the role RDz plays in doing work with Web Services

7
The Promise of Services and SOA (Service Oriented
Architecture)
Services are the driving business system design paradigm of the day.

Services – Generated by RDz provide a cross platform language for business

oriented development

Services and SOA are based on the concept of “Service Oriented Design”
At development time… Leverage external web services…
 Focus on the business logic  Service Interfaces
 Implement SOA design elements: services and interfaces  Represent external web services
 Leverage existing business developers for new SOA  Are created via import from WSDL
development  Allow the RDz developer to stay within the
 Ignore deployment targets/technology while coding/testing context of the RDz programming model

RDz SOA for WAS, CICS, System i Consume external services

Deploy Web Services… W
External
To any platform RDz RDz S
Web
 Java to WAS/Tomcat/etc. Service Interface D
Service
RDz L
 COBOL to CICS, iSeries
Records
As…
 A Web Service (uses SOAP) RDz
 A private service (uses CICS ECI, J2C, or TCP) Service
 Other SOA runtimes when they reach critical mass

Deploy Services as Web Services WSDL

External Applications
8
At a Very High Level
What we’re ultimately getting at here is a decoupling of application requester
from the application provider. And the placement of an intermediary function
to make things more flexible and dynamic:

Passing of an agreed-
to request in
Intermediary
message format Function

Simple forwarding
or
Complex message
transformation and
protocol remapping

Return of information in the

form of an agreed-to
message response

© 2008 IBM Corporation

9
What’s Behind This … Why Are We
Talking About This
Over the years our application systems have become very complicated, with
tightly-coupled relationships that are often little understood.

Actual application architecture

map from real-life customer

Two basic problems:

Changes to any part of
1. Inflexible connectivity definitions
this are …
(hard-coded, deeply imbedded in • Difficult to determine what
code) impact there is on other
2. Knowledge of relationships lost components
over time
• Expensive to analyze, often
Possible third: duplication of
resources because reuse
expensive to implement
difficult in this environment • Delays often result in missed
opportunities

Two objectives: eliminate tight (hard-coded) interconnections, and create a

way for one program to dynamically seek, find, and bind to another.

© 2008 IBM Corporation

10
A “Service” – Conceptual Definition
A discrete set of business or technical functionality that can be identified, has
a defined set of input and outputs, and is reusable
Discrete – can be contained within a definite and known “fence”
Identified -- it’s recognized as a service and people acknowledge it as a service
Defined – the input and the outputs are known and understood
Reusable – is not just a one-time thing

Service
Input “Producer”

Interface
User Exactly how the service
“Consumer” is implemented behind
the interface doesn’t
Implementation
really matter to the
Output
consumer of the service

There’s nothing revolutionary about this. What’s different is that we’re coming to a point
where improvements in technology have allowed us to do this better than before:
• Settled on a universal and common networking protocol -- TCP/IP
• Networking bandwidth is increasingly available, cheap and reliable
• The idea of “industry standards” has matured and is embraced rather than resisted
• Java as a platform-unaware language has opened up a new world of interoperability

© 2008 IBM Corporation

11
An Example - Currency Exchange
IBM’s Travel Expense Reimbursement application does not do its own foreign
currency conversions … it uses an external service for that:

No
Currency = $US? [ £100,$US,15-June ]

Interface
Internet
Yes

$US [ $196.00 ]
Implementation

Could IBM have coded an internal subroutine to do currency conversions? Sure. But very good
converters exist on the web and in this case IBM took advantage of them.

For this to work, several things need to be in place:

• IBM application needs to know about the service and where it is located
• IBM application needs to know the interface requirements: parameters, sequence, format

Understanding what services are available, where they’re located and what
interface requirements they have is a key aspect of SOA.

© 2008 IBM Corporation

12
Another Example - CICS Web Service
We’ve not really defined what a “web service” is … but for now be aware that
CICS has the ability to front-end existing CICS programs with a web service
interface … “exposing” the CICS program as a service:
Traditional
access
Appl unaffected

EXCI 3270
CICS V3.1

SOAP/HTTP

Interface
CICS Web Existing
Web Service Service CICS CICS program
Client Network unchanged
Front-End Program
Program

New front-end
allows service
oriented
invocation

Key point is that a traditional CICS program can be turned into a message based
“service” which can then be used by “service consumers” in your network

© 2008 IBM Corporation

13
Service Oriented Architecture
From www.ibm.com
Service oriented architecture
(SOA) is a business-driven IT
architectural approach that
supports integrating the
business as linked, repeatable
business tasks, or services.

An exact definition is probably not all that important. It's more

important to understand:
• The concept of a “service”
• The implied value of a loosely coupled “service” rather than a tightly coupled connection to
another application’s interface … flexibility
• That “SOA” is a path towards the use of more and more services in your I/T architecture …
not a “thing” or an “all-at-once” proposition
• That there’s more to it than just services.
© 2008 IBM Corporation
14
CICS is an Application Server
CICS is a system that hosts applications, and provides a rich set of “services”
which the applications may make use of:

CICS These are the

COBOL “CICS Programs” “existing assets”
we’re looking to
Program PL/I “expose” as
Access services
Java EJBs
Assembler C/C++
JVMs

External Data
“EXEC CICS” API C++ classes for CICS JCICS classes for Java
CICS EJB Support Resources
(transparent mapping)

CICS Services

There are many ways to access programs running in CICS -- 3270 terminal,
EXCI or EPI, RMI/IIOP, MQ, HTTP. Our focus here is going to be accessing via
Web Services.

© 2008 IBM Corporation

15
Provider vs. Requester -- CICS Can Do
Both
We typically consider CICS as a provider of web services:

Web CICS
Service The case where existing (or new)
Client CICS applications are exposed as
Appl reusable services.

But it can also be a consumer (or requester) of web services:

External
CICS Service

Web This web service could be

Appl Service anywhere accessible to CICS --
Client
inside your company or outside

We’ll focus on the top one for the most part. The concepts you’ll see are mostly
applicable to both environments. See “CICS Web Services Guide” (SC34-6458) for more.
CICS as a Web Service Provider …
© 2008 IBM Corporation
16
CICS as a Web Services Provider
Three basic requirements of being a Web Services provider:
Ability to receive the SOAP request
Standard ways: SOAP/HTTP or SOAP/JMS
Ability to read and understand the contents of the SOAP request
XML parser along with implementation of the “WS-basic” standards

Ability to act upon the request

This is the “behind the interface” implementation we’ve shown before

CICS
HTTP
Built-in SOAP Custom CICS
Handler Program Transaction
MQ

This is defined within something called a “Pipeline,” which is a structure

within CICS that invokes your customized program(s).
This is what does the mapping of XML to application data structure and
invokes the CICS transaction.

© 2008 IBM Corporation

17
CICS Web Services Development Tools
There are two primary tools used to develop CICS web services:

1. CICS Web Service Assistant

Consists of a set of JCL batch utilities that generate program components
 DFHLS2WS – Transforms a language structure into a Web Service Binding File and a Web Service
Description (WSDL). Use this to put a web service front end on an existing application.
 DFHWS2LS - Generates a Web Service binding file from a Web Service description (WSDL). This utility also
generates a language structure that you can use in your application programs. Use this to create a new
CICS application based on a WSDL, or to enable CICS to be a web service requester

2. Rational Developer for System z (RDz)

An Eclipse-based tool for zSeries development (not just web services), it does what CICS
Web Service Assistant does with additional flexibility and capabilities.

RDz is the more powerful alternative.

CICS Web Service Assistant should only be used for basic
web services enablement and when Eclipse expertise is
lacking
© 2008 IBM Corporation
18
What’s Produced by RDz for Web
Services
The process of creating and defining a Web Service to CICS

to RDz
r down bility
Transfe d -dr op capa
imple d
rag-an z/OS
RDz Using s
System

COBOL source, including

Import COPYBOOK of existing
into RDz
CICS application

Run through
the creation Tran
sfer
wizards back
COBOL source to our new Compile this into
handler, which converts SOAP the CICS LOADLIB
XML-to-COMMAREA and vice-
versa
WSBIND file, which is a binary file Optional used to
that contains information about the define the CICS
More complex scenarios can service, including the “URI
URI Map”
Map that pipeline entries
occur, of course. But this triggers the execution of the pipeline
and web service
illustrates some essential
elements of the process

© 2008 IBM Corporation

19
The Importance of XML in Web Services

You will see that XML is the common mechanism to exchange information in a
web services environment. What is XML, and why is it valuable?
A series of “tags” that mark the beginning and end of
<SOAP-ENV:Envelope> blocks of XML
<SOAP-ENV:Body> It holds both the data, as well as description of the data
<CustNo> provides an indicator of what the data is; “3” is the actual
<q0:DFHCOMMAREA> data.
<CustNo>3</CustNo> It is both machine readable and human readable, which
</q0:DFHCOMMAREA> makes things relatively easy to understand
Contrast with bit-format protocols, where bits within bytes meant certain
</SOAP-ENV:Body> things. Machine readable yes; human readable less so.

</SOAP-ENV:Envelope> Characters use “Unicode” encoding, which means it’s

universally understood
As opposed to the old EBCDIC vs. ASCII debates
Example of XML SOAP envelope
we’ll use in one of the labs

XML is “Self Describing” XML can be “parsed”

Something called a “Schema Definition” (XSD) is If a program knows what tags to
used to tell a program what XML tags to expect. expect (the WSDL supplies this),
The WSDL file (more in moment) has XSD then the program can “parse”
information (extract) information from the XML.

20
“SOAP over HTTP”

You’ll frequently hear this phrase. What it’s referring to is the passing of an
XML document -- a SOAP “envelope” -- using the HTTP protocol

Web Service XML File Web Service

Client Provider

HTTP Protocol
(TCP/IP Network)

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:q0="http://www.WBCSCUSTI.com/schemas/WBCSCUSTIInterface"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<SOAP-ENV:Body>
<q0:DFHCOMMAREA>
<CustNo>3</CustNo> The SOAP input for our CICS lab
</q0:DFHCOMMAREA> Knowing the layout is not that important to
</SOAP-ENV:Body> us at this point
</SOAP-ENV:Envelope>

The key is that the client program knew what the provider expected -- what data
elements and what XML tags to use. How did it know that? It had the WSDL file.

The Web Service Description Language (WSDL) file …

21
The WSDL File
WSDL contains information about the service -- where it’s located, what
parameters it takes as input, what it gives back as output, what XML tags to
use, etc. It is sometimes known as a “bindings file”.
It can be long and complicated … what follows is a boiled-down snippet to show essence
<complexType name="DFHCOMMAREA">
<sequence>
<element name="CustNo">
<simpleType>
<restriction base="int"/> Client knows input XML and
</simpleType> data requirements based on this
</element>
</sequence>
</complexType> Client knows where service
What service will return was here … removed to save space
is located based on this

<wsdl:service name="WBCSCUSService">
<wsdl:port binding="tns:WBCSCUSBinding" name="WBCSCUSPort">
<soap:address location="http://mig.null.washington.ibm.com:12301/WBCSCUST"/>
</wsdl:port>
</wsdl:service>
Web Service
<SOAP-ENV:Body>
Provider
<q0:DFHCOMMAREA>
<CustNo>3</CustNo>
Web Service </q0:DFHCOMMAREA>
Client </SOAP-ENV:Body>

Where does WSDL come from? …

22
WSDL File is a Product of RDz

You could hand-code the WSDL.

More likely you’ll use a development tool (in our case, RDz)
to create the web service, and RDz will also produce the
WSDL.

Web Service
Service Program Provider

With WSDL, client

knows where service
is and how to drive it
WSDL File Web Service
• Rational Application Developer Client

• WebSphere Developer for zSeries

• Other Development Tools

23
 That's all well and good, but what about
performance? That’s .1 second
http://listserv.uga.edu/cgi-bin/wa?A2=ind0908&L=CICS-L&D=0&P=30338
1/10th of a second

Any other questions about "Why Web Services"?

24
Topic objectives
After having completed this topic, you now should be able to:
Describe the foundation SOA terms and vocabulary:
 Service
 Service Oriented Architecture
 Web Service
Describe the role CICS can play, in a Service Oriented Architecture
Define the purpose of XML
Differentiate between:
 Service
 WSDL
 XML
 SOAP
Describe the role RDz plays in doing work with Web Services

25
Unit
RDz and Services
(SOA)
Topics:
 XML and Web Services Terms and Concepts
 RDz and Web Services
 Setting up for Web Services
 Creating and consuming an RDz Web Service
 Consuming a 3rd Party Web Service

26
UNIT RDz Introduction

Topics:
• The RDz Workbench – Terms and Concepts

• Editing COBOL Programs

• Debugging COBOL Programs

 Appendix – Creating a New Workstation Project

 Appendix – ISPF/LPEX Editor Comparison

27
 Service Oriented Design – Concepts
 Service Orientated Design is a software design paradigm that encourages the creation of functionally discrete (modular) business logic,
composed of standardized software components (logic routines and subroutines with standard interfaces)

 Services are software components that:

 Are logically separated, along the lines of a “business service” – such as:
 Rent a car – which is further de-composed into:
– Reserve a vehicle – consisting of lower-level services such as:
– Confirm a location
– Confirm the customer information
– Get payment information
– Confirm customer and payment information
– Create the reservation
…

 Services are formally declared with a standard network interface that allows them to be invoked by other services that only know the interface.
 Also, services:
 May be created at various levels of business/technical granularity (i.e. low-level vs. high-level)
 Can be assembled/combined (“choreographed”) to create higher-level business functionality
 Can be deployed to any platform – independently – and called from any platform through their network interface

28
 What is a Service? Network Interface Definition
 “A Web Service is a network interface to programs that live on a particular machine implemented in such
a manner that any other program (or many programs) running on any other machine, written in any
language, and running on any OS can call it.”

 Additionally:
Services are an abstract design pattern - they are not the same as Web Services In fact, a service can be implemented using a number of different technologies, including:
 .

 RPC (Remote Program Call) - which you implement with an RDz:

Local Service …or…
–
Library call …or…
–
Program
–
 DCOM (Distributed Component Object Model)
 REST (Representational State Transfer)
 CORBA (Common Object Request Broker)
 Web Services – which you implement with an RDz Service part

 The “network interface” for a Web Service is formally termed a WSDL

 Web Services Description Language

29
 Creating and Consuming Services – WSDL Files and RDz Generation

 WSDL is an XML document used to describe and locate Web Services.

 A WSDL:
 Specifies the run-time location as a URL
 Specifies operations and data in the Web Service
 Is written in XML using the SOAP transport protocol

 But you don’t want to:

 Learn XML or SOAP or…
 Create the WSDL files manually 

 You want to code COBOL, PL/I and HLASM business logic – exactly as you’ve done all along in this course 

 So in fact, the RDz tooling will generate all of the “plumbing” for you – when you create or consume Web Services:
 When you create an RDz service, the tooling generates WSDL files, so you will not need to learn XML (and other low-level languages, terms and concepts)
 When you consume a service, RDz generates RDz Interfaces from existing WSDL files for you – automatically

30
Reusing Existing Application Resources

You can do this either directly or indirectly using a wrapper program:

Existing Application If your app is not well

structured (comm logic
Communication integrated with business
CICS Logic logic) it might not be a
good candidate for
being exposed as a web
EXEC
CICS LINK
service

EXEC CICS LINK

Business
Pipeline Logic
HTTP
Built-in SOAP Handler EXEC CICS LINK Greater control over
Handler Program interface exposed as
MQ web service
Wrapper Ability to expose
Program multiple CICS trans as
a web service

This is listed as a “best practice” in the following redbook:

Application Development for CICS Web Services

SG24-7126

Application Aggregation …

31
Different Architectural Approaches to CICS and Web Services

WebSphere z/OS
HATS
CICS

Applications
BMS (3270)
1
TN3270

2
Web EXCI
Service
Client Java

Applications
COMMAREA
SOAP/HTTP

SOAP/MQ
3

1. SOAP/HTTP to Host Access Transformation Services (HATS), an application that runs in WebSphere and provides
a web service interface (or browser interface) for BMS (3270) applications in CICS
2. SOAP/HTTP or SOAP/JMS to custom web service running in WebSphere.
3. Web service interface running inside of CICS, and accessed either through CICS HTTP listener (or MQ)

32
The COBOL Café and Rational - z/OS Product
Training from IBM
http://www-949.ibm.com/software/rational/cafe/community/cobol

 To become more innovative and more competitive, companies know that

education – in all forms is necessary - today more than ever.
 To help, IBM has implemented solutions that feature community-based
knowledge sharing - that give your developers instant, secure access to
shared content, and expertise in:
 COBOL / IMS / CICS / DB2 and z/OS Technologies
 Rational Developer for System z (RDz)
 Rational Asset Analyzer (RAA)
 Check out the COBOL Café
http://www-949.ibm.com/software/rational/cafe/community/cobol
 And check out upcoming free, self-paced IBM training in:
 RDz / RAA / COBOL / IMS / CICS / DB2
33