IBM WebSphere Studio Enterprise Developer

V5.0
XML Enablement and z/OS Web Services

Mark Evans
WebSphere Studio Enterprise Developer and VAGen Development
evansm@us.ibm.com
Agenda
Brief Introduction to Web Services
Why a need for z/OS XML Enablement?
z/OS XML Enablement
Benefits
Usage Scenarios
A look at the XML Enablement tool
Prerequisites
Using in a Web Service
Summary

WebSphere software
 Web Service Definition
Examples
Business information
Self-contained, self-describing, modular with rich content
weather reports
applications that can be published, located, stock quotes

and invoked over a network, generally, the airline schedules

credit check
Web. news feed

Communicate via XML messages Transactional Web

Services for B2B, B2C
airline reservation

A web service is composed of: rental car agreement

supply chain mgmt
An interface that defines methods (portType) Business process
An implementation that will contain the actual externalization
business logic and functionality business linkage at
workflow level
complete integration at
process level

WebSphere software
 Web Services Participants and their Roles
Broker
Maintains Web Services Registry
where services are published and
found.

WSDL and UDDI UDDI and WSDL

1
2
Provider User
Provides e-business services and FINDS required services in Web
PUBLISHES availability of these SOAP
Services Registry, BINDS to those
services to Web Services 3 services in applications.
Registry.

Makes use of XML messaging via Simple Object Access Protocol (SOAP)
WebSphere software
 What is WSDL?
Web Services Description Language
WSDL is an XML based vocabulary for defining a Web Service:
interfaces
operation types (i.e. one-way, request-response, notification)
messages defining a Web Service interface
HTTP
definition of data types (XML Schema) (SOAP)

access protocol (i.e. SOAP over HTTP)

contact endpoints (i.e. Web Service URL and URNs1)
A Web Service URL returning WSDL makes Web Services
self-describing
Similar in purpose to IDL (Interface Definition Language)
From a WSDL file, wizards can generate:
proxy classes for calling Web Service
skeleton classes to implement a Web Service

WebSphere software
What is SOAP?
Simple Object Access Protocol
SOAP is an XML based protocol for communication between two
remote applications:
is based on RPC messaging
is language independent (de-couples interface from implementation)
represents remote procedure calls and responses
A SOAP message consists of:
envelope
wraps the message itself
defines rules for decoding the message
message
request
method to invoke on a remote object and parameters
response
result of running the method and exceptions

WebSphere software
 Problems Solved by Web Services

Allows heterogeneous systems to communicate with

each other
i.e. A windows client could access a web service running on a main frame

Customers can find services based upon the service type

Similar to finding a list of landscapers in the phone book

Allows different organizations to communicate

Enables applications to talk with each other

WebSphere software
WebSphere software

XML Enablement for z/OS

What is z/OS XML Enablement?
Enables COBOL-based applications to consume and produce
XML messages
Leverages XML parsing capabilities of IBM Enterprise COBOL V3.1

Creates COBOL converter programs

Inbound to convert XML messages into native COBOL data
Outbound to convert native COBOL data into XML messages

Creates template COBOL driver program

Illustrates the invocation of converters
Illustrates the interaction with existing application
Needs to be updated before run

Enables communication with XML based systems

WebSphere software
XML Enablement
Enables COBOL-based applications to consume and produce XML
messages
Original COBOL program unchanged

COBOL Input converter

Data declarations
(or complete Output
program) converter

WebSphere Driver program

Studio
Enterprise
Developer
XML Document schema
Enablement definition (.xsd)

WebSphere software
Benefits of XML Enablement
Enterprise Modernization:
Easy to "reface" existing COBOL applications to support XML messages

Programmer Productivity:
Converter programs are generated to easily convert between XML and COBOL
datatypes
Template program generated which illustrates how converter programs are used with
existing COBOL
Exploits customers' existing assets/skills/literacy

Performance
XML parsing/conversions run on z/OS

Eliminates the requirement of having a rigid, binary interface for legacy

COBOL and PLI programs.

Supports multiple runtime scenarios

Including web services
WebSphere software
 XML Enablement - Runtime Scenarios

CICS/IMS systems
WebSphere

XML Scenario #1 SOAP server CICS/IMS Txn

JCA Built from
Web Service generated driver
XML
XML Based Template
converter
Application

nario #2
Sce
Batch Call

XML Scenario #3 New COBOL app Data

Built from generated Call
driver template
XML Based XML
converter Data
Application Existing
COBOL
app/tran
WebSphere software z/OS
 Using the XML Converters
Driver Inbound

Local-Storage Section.

Inbound
1 business-datastructure.
2 coordinates occurs 5 times. XML To Data
3 x pic 9(4)v9(4) binary. Structure
3 y pic 9(4)v9(4) binary.
XML Bytes 3 z pic 9(4)v9(4) binary.
Converter

Linkage Section.

Count XML Bytes

1 XML-Interface.
2 XML-length pic 9(9) binary.
1
Business Program
2 XML-Bytes pic x(1048576).

Business Program
Procedure Division.
call 'inbound' using Business
business-datastructure Program
XML-length xml-bytes 2 Being XML
XML Bytes
Enabled
call 'busprog' using
business-datastructure

Count XML Bytes call 'outbound' using

business-datastructure
3 Outbound
XML-length XML-bytes

Outbound
Data
goback
Structure To
XML
Converter
WebSphere software
Without z/OS XML Enablement - Java Enabled CICS
Model

View
CICS TS
Controller
4
BIN legacy
JCA program
6 5 DB2
3 7

EJB
01 DFHCOMMAREA.
Rigid Data Structure
2 8 05 ACTION PIC X(10).
05 STATUS1 PIC X(1). Tightly Coupled
05 SYMBOL PIC X(5). Components
Action 05 PRICE PIC S9(8)V9(2). Cumbersome to modify
05 DETAILS PIC X(20).
Servlet
1 9
Serialized Input
GETPRICE S:120
JSP
Serialized Output
GETPRICE 0S:120
GETPRICE 0S:120 10525A fortune
10525A fortune 500
500 Company
Company

WebSphere software
When input to legacy program is XML
<?xml version="1.0" encoding="UTF-8"?>
<DFHCOMMAREA>
<action>GETPRICE</action>
<status1>0</status1>
<symbol>s:100</symbol>
<price>88.25</price>
<details>A Fortune 500
Company</details>
</DFHCOMMAREA>

Self Describing Data (loosely coupled)

De-couples Caller (e.g. EJB and JCA for legacy CICS txn)
These components are just dealing with a "string buffer"

Easily enhance...client sends additional fields and CICS transaction

can process or ignore
WebSphere software
General Limitations
Workbench
MVS Project cannot be source and target (must use local project)
Copy books must be fully expanded
z/OS Runtime
Usage "COMP-X" not supported
Error handling via Language Environment exceptions
Mapping of XML Element attributes not supported
REDEFINING items are ignored
Inbound message processing
Occurs-Depending-On (ODO) is supported
No validation that group repetitions don't exceed depending on variable
Entire XML message must be scanned
Outbound message generation
Complex Occurs-Depending-On (ODO) not supported
WebSphere software
Early Availability Limitations
Workbench
No online help
XML for the Enterprise white paper

Inbound message processing

Unicode UTF-16 is not supported

Outbound message generation

Simple Occurs-Depending-On (ODO) not supported
Trailing/leading blanks in character content not removed
Trailing/leading zeroes in numeric content not removed
<, >, ', ", & not allowed in character content

All of these removed at General Availability

WebSphere software
Using the Generate XML Converter Wizard

WebSphere software
Using the Generate XML Converter Wizard ...

WebSphere software
WSED XML Enablement Wizard - Example output

Generated files

converter prgm
driver prgm
original cobol prgm

xml schema

WebSphere software
Creating a z/OS Web Service
Legacy Program is now enabled to accept XML documents

Can use Web services wizards within WebSphere Studio

From EJB or Javabean used for wrapper invocation of legacy code
From Javabean using generated XSD schema from XML Enablement tool

At General Availability, WSAD-IE z/OS Web Service wizards

Creates artifacts based on generated COBOL driver program from XML
Enablement tool (or other COBOL programs)
WSDL
Service Proxy
JCA Connector code

WebSphere software
XML Enablement Runtime Scenario and Web Services
zOS EIS
WebApp Server
UDDI may be consulted to TCP/IP CTG
dsicover the service at application JCA XML IMS
Connector High
build or runtime. Connect XML performance
XML Parser

UDDI WSDL file describing this service Schema

is registered in UDDI prior to discovering conforming XML
and invoking the Service.
Converter
WSDL

ServiceProxy Driver
Transaction
Service Proxy may be concrete
(static binding) or generic Schema XML
(dynamic binding) conforming XML
COBOL

XML Inbound "XML/SOAP"

XML
Converter
pass-thru
Web Service Servlet
E.g. SOAP via HTTP
Request
XML Outbound Legacy
Transaction/COBOL
Business logic
Legend:
CICS TS
Artifacts generated/provided by IMS
WSAD-IE

Artifacts generated by WSED XML

Enablement
WebSphere software
Legacy Call Center
(3270)
 XML Enablement Runtime Prerequisites
Prerequisites
IBM Enterprise COBOL for z/OS and OS/390 Version 3 Release 1 (program number
5648-A25) or later

IBM Language Environment for OS/390 Version 2 Release 10 (program number

5647-A01) or z/OS V1.1 or later with PTF for APAR PQ65085 (Available Sept. 2002)

OS/390 R8/R9/R10 and z/OS V1R1 support for Unicode ™ is required for the XML
converters generated by WSED General Availability release.OS/390 R8/R9/R10 and
z/OS V1R1 support for Unicode ™ can be obtained free of charge at
https://www6.software.ibm.com/dl/os390/unicodespt-p . This support is integrated into
z/OS Version 1 Release 2 and later.

IBM WebSphere Studio Enterprise Developer (WSED) for Multiplatforms Version 5 Early
Availability (EA) (program number 5724-B67) or later

WebSphere software
 Summary

Facilitate enterprise modernization by refacing existing COBOL

applications to support XML messages

Achieve significant productivity gains by utilizing the converter and

driver template generators

Gain performance benefits by running XML parsing and conversions

on the z/OS systems

Enable development of Web Services for z/OS applications

WebSphere software
WebSphere software

XML Enablement for z/OS

Backup Charts
XML Parsing Flow

WebSphere software
COBOL Compiler Support for XML
Introduced with IBM Enterprise COBOL for z/OS and OS/390 V3R1
High-speed XML parser
Consumes inbound XML messages
Verifies well-formedness
Transforms contents into COBOL data structures
Supports XML documents encoded in Unicode UTF-16, EBCDIC, ASCII
New XML PARSE statement
Begins XML parse
Identifies document to be processed
Identifies processing procedure
Processing procedure
Controls the parse
Receives and processes XML events
Handles exceptions
WebSphere software
 XML Document Defined in Working-Storage
******************************************************************
*XML document,encoded as initial values of data-items.*
******************************************************************
1 xml-document.
2 pic x(39)value '<?xml version=“1.0 ”encoding=“ibm-1140 ”'.
2 pic x(19)value 'standalone=“yes ”?>'.
2 pic x(39)value '<!--This document is just an example-->'.
2 pic x(10)value '<sandwich>'.
2 pic x(35)value '<bread type=“baker&apos;s best ”/>'.
2 pic x(41)value '<?spread please use real mayonnaise ?>'.
2 pic x(31)value '<meat>Ham &amp;turkey</meat>'.
2 pic x(40)value '<filling>Cheese,lettuce,tomato,etc.'.
2 pic x(10)value '</filling>'.
2 pic x(35)value '<![CDATA [We should add a <relish>'.
2 pic x(22)value 'element in future!]]>'.
2 pic x(31)value '<listprice>$4.99 </listprice>'.
2 pic x(27)value '<discount>0.10</discount>'.
2 pic x(11)value '</sandwich>'.
1 xml-document-length computational pic 999.

WebSphere software
 Data Definitions for XML Content

******************************************************************
*Sample data definitions for processing numeric XML content.*
******************************************************************
1 current-element pic x(30).
1 xfr-ed pic x(9)justified.
1 xfr-ed-1 redefines xfr-ed pic 999999.99.
1 list-price computational pic 9v99 value 0.
1 discount computational pic 9v99 value 0.
1 display-price pic $$9.99.

WebSphere software
Parsing XML Documents

XML PARSE xml-document

PROCESSING PROCEDURE
xmlevent-handler
ON EXCEPTION
DISPLAY 'XML document error'
XML-ERROR
STOP RUN
NOT ON EXCEPTION
DISPLAY 'XML document was
succesfully parsed.'
END-XML

WebSphere software
XML Processing Procedure
xmlevent-handler section.
evaluate XML-EVENT
*==>Order XML events most frequent first
when 'START-OF-ELEMENT'
display 'Start elementtag:<'XML-TEXT '>'
move XML-TEXT to current-element
when 'CONTENT-CHARACTERS'
display 'Content characters:<'XML-TEXT '>'
*==>Transform XML content to operational COBOL data item...
evaluate current-element
when 'listprice'
*==>Using function NUMVAL-C...
compute list-price =function numval-c(XML-TEXT)
when 'discount'
*==>Using de-editing of a numeric edited item...
move XML-TEXT to xfr-ed
move xfr-ed-1 to discount
end-evaluate
when 'END-OF-ELEMENT'
....

WebSphere software