1. EGL Integration with COBOL and Web Services
Mark Evans EGL Development

2. © Copyright IBM Corporation 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.

3. Agenda Brief Introduction to Web Services
RBD/EGL – A tool for Building Web Services
Options for EGL Integration with COBOL Web Services

4. Enterprise Modernization – Why Web Services ?
Web services provide standardized access to assets for different software applications residing on disparate platforms
Web service definitions provide abstract interfaces which allow for loose coupling between business components – implementation can vary without affecting consumers
You can reuse applications exposed as Web services in a variety of service-oriented architecture frameworks, such as a process choreographer or an enterprise service bus.

5. Enterprise Modernization and Web Services
Basic Problem Statement:
An Existing COBOL program on CICS contains the business/data logic for a business transaction
A requestor/client outside CICS needs to obtain this information
Solution
Create Web Service to “front end” the called program
Provides standard interface
Many tools work with and can access web services
CICS TS 3.x or Later
Requester
Needs info
From CICS
Callable
COBOL
Program
Web Service
DB2 Or
Files

6. Enterprise Modernization and Web Services – Getting Started
What’s Required?
Standard Definition of the Services interface
SOAP format to contain the messages going back and forth
WSDL (Web Services Definition Language) to define the message content
A Web service (SOAP message) processor such as one of the following:
WebSphere Application Server
CICS
Tomcat
Other application servers
Tools to help build the necessary interfaces and work with the runtimes
CICS TS 3.x or later
CICS
Web
Service
Runtime
Callable
COBOL
Program
DB2 Or
Files
Requester
Needs info
From CICS
SOAP Message/WSDL
Web Service
WebSphere
Web Service
Support

7. Agenda Brief Introduction to Web Services
RBD/EGL – A tool for Building Web Services
Options for EGL Integration with COBOL Web Services

8. EGL Services Support – High Level View
At development time…
focus on the business logic
implement SOA design elements: Services & Interfaces
leverage existing COBOL or RPG developers for new SOA development
ignore deployment targets/technology while coding/testing
Use Deployment Descriptor file to describe Deployment considerations
Use existing non-EGL Web Service
Create EGL Interface and EGL Records automatically based on existing WSDL
EGL
RUI/JSF/TUI W S D L
EGL
Interface
Existing Service
EGL
Records
EGL applications invoke operations in EGL Interface and send Records as parameters
EGL
Service
EGL
Records W S D L
Non-EGL
User of
EGL Service
Deploy EGL Services…
in Java to Java to WAS, Tomcat, Win, Linux, HP-UX, Solaris, iSeries
in COBOL to CICS, System i
Build & expose EGL Web Service

9. Service Part – Built into the language
A service is similar to a library, with the major exception that a service may be located remotely from its client.
The client – which can be a program, JSF handler, library, or other service - uses (invokes) the functions defined in the service.
Services have one or more public functions that contain business logic. Once you have written the business logic, you can deploy the service as one of the following:
an EGL Java™ service
a Web service
an EGL COBOL service
a CICS® Web Service
In general, you create a Service part when you want to make your business logic available to other programs, either locally or remotely, in an encapsulated way.
 Notes:
Example of an EGL Service

10. EGL Interfaces - Concepts built into the language
SOA
EGL Interfaces - Concepts built into the language
Interface part
Provides abstract definition of Service
Can be created directly from WSDL for use by Web Service clients
Access external services as EGL services
Interface IStockQuoteService Function getQuote(symbol String) returns (money);
end Service StockQuoteService implements IStockQuoteService Function getQuote(symbol String) returns (money) …
end

11. EGL Services – EGL Deployment Descriptor Files
EGL Deployment Descriptor files are used to describe how EGL service applications are bound to the clients that call them, and vice versa
Generates wrapper program for each service
Service Client Bindings
How to invoke the service
Services Deployment
How the service is invoked
Sharable Protocols
Common information for clients and services

12. Agenda Brief Introduction to Web Services
RBD/EGL – A tool for Building Web Services
Options for EGL Integration with COBOL Web Services

13. RBD/EGL SOA Integration with Enterprise Programs – Options
CICS TS 3.x or later
Web Service Based Option 1
RDz
Generated Handlers
Callable
COBOL/EGL
Program
CICS
Web
Service
Runtime
Channel
Web Service Based Option 2
Cobol Call
EGL and non-EGL client
EGL
COBOL
Web Service
Wrapper
EGL
COBOL
Service
Web Service
Requester
Channel
Cobol Call
SOAP Message
WSDL
Service Invocation
WebSphere
EGL
Client
Call Interface Based Option 3
CICSECI or CICS J2C
Call Statement

14. Web Service Based Option 1
RBD/EGL SOA Integration – Option 1 EGL Integration with RDz Generated WSDL/Handlers
CICS TS 3.x or later
Web Service Based Option 1
CICS
Web
Service
Runtime
Callable
COBOL/EGL
Program
RDz
Generated Handlers
Channel
Web Service
Requester
SOAP Message
Cobol Call
WSDL
EGL and non-EGL client
Use Rational Developer for zSeries tools to:
Create WSDL and/or WSBIND needed by CICS Web Services Runtime
Create COBOL “wrappers” to front end the COBOL program
More on this later
Use EGL to:
Create an EGL interface from the RDz generated WSDL
Create a client binding (how to invoke the service) in the EGL deployment Descriptor
Create a EGL Client (e.g. Service) to invoke this interface

15. Create web services for zOS runtimes – RDz* Tooling
Build, Deploy, and Test Web services from existing applications
Create source code skeletons from web service definitions
Map web service definitions to existing application modules
Supports traditional languages
COBOL
PL/I
Supports zOS specific runtimes
CICS
IMS
Batch
*RDz = Rational Developer for system z 15

16. Consuming EGL Web Services – Create Interface and Client bindings
Copy the WSDL from RDz into the EGL project
Select the WSDL file and choose:
“Create EGL Client Interface”
Choose which web service you want to interface with (Next)
Choose (filled in for you based on WSDL)
Location of source
Which functions to interface with
Click “Next” to specify client bindings

17. Consuming non-EGL Web Services – Resulting Definitions
Need to fill in URI with URL used to invoke the web service

18. EGL CICS Web Service Client
CICS TS 3.1
CICS
Web
Service
Runtime
EGL COBOL
Program or
Service
(including
3270 pgms)
COBOL
Web Service
Proxy
Service
Provider
Cobol Call
Channel
SOAP Message
HFS
WSDL
Notes:
We generate the web service proxy for any program that needs to invoke a service (as a client)
WSBIND
Generated from the EGL deployment Descriptor (web service client bindings)

19. Web Service Based Option 2
RBD/EGL SOA Integration – Option 2 Using EGL Web Services to create new logic or wrapper existing programs
CICS TS 3.x or later
Callable
COBOL/EGL
Program
Web Service Based Option 2
CICS
Web
Service
Runtime
Web Service
Requester
Cobol Call
SOAP Message
EGL
COBOL
Web Service
Wrapper
WSDL
Channel
EGL
COBOL
Service
Cobol Call
EGL and non-EGL client
Use RBD/EGL to:
Create a service part (see previous slides)
Service part calls native COBOL program
Add EGL Service Binding information to the EGL Deployment Descriptor
Generate EGL service and Deployment Descriptor which creates
WSDL and WSBIND needed by CICS Web Service Runtime
COBOL modules to implement the EGL COBOL web service

20. EGL CICS Web Services – Generation Process
Deployment Descriptor file
(.egldd file)
HFS
WSBIND
WSDL
Build Descriptor file
(.eglbld file)
EGL Build
Server
CICS
Generation
Services Source
(.egl files)
z/OS
PDS w/Load
Modules
Workstation
z/OS
Deployment Descriptor File  WSBIND, WSDL, & Wrapper COBOL programs
Services  COBOL program

21. EGL CICS Web Services – Deploying Service on CICS
For resulting load modules:
In CICS DFHRPL;
Add PDS with load modules for service and service wrapper
Add EGL COBOL Runtime library
In CICS CSD
Add CICS Program entries (unless dynamically created)
Add any required DB2 related entries if program accesses DB2
Install CICS groups/entries as necessary
Perform CICS NEWCOPY if replacing existing load modules
For Web Services Infrastructure:
Add CICS Pipeline Entry to specify target HFS directories that generation writes to (one time if you want to always generate to same HFS directory)
Perform a CEMT P PIPELINE SCAN to:
Enable the Pipeline
Create WebService entry based on information in generated WSBIND file
Create URIMAP entry based on information in generated WSBIND file NOTE: CICS Userid must have permission to write to HFS directories specified in Pipeline definition
If using Transaction other than CPIH in Web Service Entry
Recommended if using EGL generated Web Service
Still must be associated with same program example as CPIH
Can be done by CEDA COPY command:
CEDA COPY TRANSACTION(CPIH) GROUP(DFHPIPE) AS(<newname>) TO(<group>)
Install CICS group/entries as necessary

22. RBD/EGL SOA Integration – Option 3 EGL Services and Call Interface
CICS TS 3.x or later
Callable
COBOL/EGL
Program
CICS
Web
Service
Runtime
Cobol Call
EGL and non-EGL client
EGL
COBOL
Web Service
Wrapper
EGL
COBOL
Service
Web Service
Requester
Channel
Cobol Call
SOAP Message
WSDL
Service Invocation
WebSphere
EGL
Client
Call Interface Based Option 3A and 3B
CICSECI or CICS J2C

23. EGL Services for CICS (Option 3A)
EGL also has the concept of an EGL service
Which is:
Accessing the generated service directly using
CICS ECI (remote invocation)
CICS JCA/J2C (remote invocation)
COBOL Calls
From EGL Web Service Client
EGL generated Java under WAS (libraries/services/jsfHandlers)
EGL generated Java running outside WAS
EGL generated COBOL running as 3270/CICS Batch programs in CICS
With remote invocation (CICS ECI or CICS J2C)
No XML parsing
No WSDL processing
Can utilize Channels and Containers
Data can be dynamic length (dynamic arrays, in and out types, etc)
EGL handles the data conversion
Should be better performance (less parsing)
Can use same generated EGL Service code as used through Web Services
i.e. no re-generation required

24. EGL Services vs Web Services – Controlled via Web Client Bindings
You can create multiple Web Client Bindings
Allows you to create multiple ways for the services to be invoked and
Allows service client to determine which protocol to use by
Referencing name in the service/interface declaration using “bindingKey”

25. EGL Clients – Calling COBOL/EGL Programs – Option 3B
Standard EGL Call statement identifies the program
Call “myprog” (parm1, parm2,…);
Parameters:
Can be items and/or records (up to 30)
Passed as values across network
Converted to pointers on mainframe as needed
Data converted on Client side before sending to mainframe
All are treated as in/out parameters (sent both ways)
CICS and IMS…total records can only be 32K unless channel/containers used
Data received using normal “linkage” methods for target program
EGL communications layer
Provides the interface to various target specific communication protocols
Developer does not need to know anything about:
APIs to make the remote call
How the call is physically implemented
Anything about conversions
The details of making the connection to the remote system are specified in an EGL “build file” through a linkage options part

26. EGL Clients – Calling COBOL/EGL Programs – Option 3B
Shows existing called programs in name space.
Resulting code

27. RBD/EGL SOA Integration with COBOL – Call Interfaces
z/OS
AIX/Linux/zOS
DB2
CTG Server
WAS web Services
Client
WAS server
TCP/IP
MRO/EXCI
Tcpipservice port
EGL Generated Web Service code Call Programx
EGL Generated ProgramX Or
Native COBOL Programx
J2C Config
CICS
CTG Server
Web Service is created using EGL wizard based on already created EGL Programx
No additional coding needed by programmers…just develop called program and generate needed artifact
CTG Server can reside on distributed or z/OS system…not needed on both.

28. Linkage Options Build Part Editor – Specifying the linkage option
EGL Build File 1
Program callLink
applies to
Type of callLink
Build Descriptor must associate the linkage options to use (this does not happen by default!)
So can be different ones for debugging vs deployment if you have different build descriptors
Properties vary
by type

29. Example calling COBOL/CICS from via Java J2C
WebSphere Application Server 1
LAB5SER Called Program)
CICS 2 3

30. RBD/EGL SOA Integration with COBOL – Which option?
Description
Create WSDL using RDz and use EGL to invoke this WSDL (service)
Use EGL to create CICS Based web Services
Use Application Server for Web Service and call COBOL pgm
Required Development Tool
Rational Developer for zSeries with EGL
Rational Business Developer
Infrastructure
CICS Web Service
WAS (application server)
CICS Transaction Gateway
Other Factors
Does not require a separate application server
Allows use of “native” COBOL tooling (RDz) to build required artifacts
Separate client technology tool needed
Allows development of client, service, and interaction with native program in single tool (RBD)
Defined EGL records can be used.
Allows use of existing application server if already in place
Supports both binary (CICSJ2C) AND SOAP based web service from same generated artifacts
EGL Records can be used or created from COBOL copybooks (native COBOL)

31. Let’s drill down a little more

32. Services Considerations
Services can represent a grouping of business logic:
Each function in service is a piece of logic related to the group
E.g. AccountService
GetAccount
UpdateAccount
DeleteAccount
Etc.
One function can combine multiple business functions
More on this in following slides
Make sure you use exception handling for calls to host programs
Use UI records (type basicRecords) on calls from RUI Handlers to service functions. Use different records (if needed) to call back to host programs.

33. How would the “call” be used in a service
Example: Change Amortize to call a program (on CICS) instead of calculating within it.
Uses 1 record to pass data between RUI handler and service (inputData) (flexible)
Uses different record to pass data between reused called program and service (usually fixed if from VAGen
Can be different depending on needs

34. Can also combine multiple calls from one service invocation

35. Summary Reuse of existing CICS assets is possible
Several ways to interact/reuse these assets
Combination of RDz and RBD give:
Great Flexibility in how the assets are invoked
Ability to work within existing architectures/infrastructures
The tools traditional programmers can use to build web services for the enterprise

36. Backup

37. EGL Web Services – What is generated?
CICS TS V3.1
TCPIPSERVICE
CSOL
SOAP message
CPIH/User Defined Xact
CWXN
Service
Requester
Pipeline
matching
URIMAP
URIMAP
HFS
data mapping
pipeline
config
dynamic
install
WSDL
PIPELINE
Wrapper Pgm
There are a number of interrelated resource definitions required to process a Web Service in CICS 31.
A resource definition is required to define the transport. Both http and WebSphere MQSeries can be used as transports. For http, a CICS TCPIPSERVICE definition is required. For WMQ, a request queue must be defined with a QLOCAL definition.
Next CICS must determine which Web Service is required. CICS 3.1 will use a URIMAP definition to map the incoming Universal Resource Identified (URI) to a specific WEBSERVICE definition. The associate PIPELINE definition is determined from the matching URIMAP definition.
The PIPELINE definition is used to specify which processing nodes or message handlers are to operate on a Web Service request.
The WEBSERVICE definition is used to specify how CICS is to execute the application. The WSBIND file, specified in the WEBSERVICE definition, is used to tell CICS which application program to execute, if a COMMAREA or CHANNEL is used and how CICS is to transform the message between the SOAP XML format and COMMAREA format.
dynamic
install
WSBind
WEBSERVICE
Service Pgm
Generated by EGL

38. Defining the CICS Web Services Resources
Define a TCPIPSERVICE
For Port to listen on for SOAP requests
Define a PIPELINE
To define the location of the
WSDL
WSBIND file (defines mapping of XML to data structure)
Install the PIPELINE definition and issue CEMT PERFORM PIPELINE SCAN
This does the following
Locates the WSBind file
From the WSBind file, CICS will dynamically create a WEBSERVICE resource
CICS will also dynamically create a URIMAP definition
URIMAP – URL to WebService mapping
Can define everything individually if preferred
Setting up the CICS resources is not as difficult as it might seem. It is only necessary to
define the TCPIPSERVICE (or WMQ) and the PIPELINE. Place the WSBind file generated
from the batch tooling into the HFS directory specified in the PIPELINE definition. Then
either install the PIPELINE definition or issue a CEMT PERFORM PIPELINE SCAN command.
The PIPELINE definition contains the directory name where the WSBind file can be found.
From the WSBind file, CICS will dynamically create the Web Service resource definition.
This provides CICS with enough information to be able dynamically to create a URIMAP
definition as well. So, as long as you create a valid PIPELINE definition and put the WSBind
file in the correct location, CICS will do the rest.
The necessary definitions can all be input and installed manually if preferred. The definitions
can be put into a group and the group installed as for any CICS resource.

39. CICS Pipeline Definition
Configuration info
Supplied by CICS
HFS location for CICS to store resource info
Location of:
WSBIND
WSDL

40. CICS URIMAP URIMAP name Relative Path in URL Transaction to Start
Created by CICS from Pipeline Definition
URIMAP name
Generated by CICS
Relative Path in URL
Transaction to Start
Pipeline to use
Service Name

41. CICS WebService Definition
Created by CICS from Pipeline Definition
Service name
Pipeline to use
URIMAP resource definition
Program to run
Wsbind/WSDL file location for data mapping