Sei sulla pagina 1di 25

DACWORKS

CICS/TS Soap XML


Developments
Developments

David Clancy
The mainframe breakfast network
5th November 2003

Nov 5th 2003 © Dacworks limited Page 1


DACWORKS

Acknowledgments
The following are trademarks of International Business Machines Corporation in the United States, other countries, or both:
IBM, CICS, CICS/TS, CICS Transaction Server, DB2, MQSeries, OS/390, Z/OS, WebSphere.

Java, JavaBeans, and all Java-based trademarks and logos are trademarks of Sun Microsystems, Inc. in the United States,
other countries, or both.

Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States, other
countries, or both.

Other company, product, and service names and logos may be trademarks or service marks of others.

Dacworks Limited,
Steepdown House,
The Crescent,
Steyning,
West Sussex,
BN44 3GD,
England,
United Kingdom.
telephone: 44 (0) 1903 814731
web: http://www.dacworks.co.uk
email: dacworks@btinternet.com

Nov 5th 2003 © Dacworks limited Page 2


DACWORKS

Introduction
IBM SOAP for CICS feature
SOAP overview
SOAP request and response examples
Inbound CICS support
Outbound CICS support
DFHWBCLI
Enterprise compilers
XML parse support
Unicode support
Message generation
Using CICS document commands
CICS/TS 2.3 enhancements
JCICS support for document commands
Summary
Nov 5th 2003 © Dacworks limited Page 3
DACWORKS

Availability
IBM SOAP for CICS feature
Delivers fully supported SOAP access to CICS
Replaces CICS Technology Preview made available as SupportPac CA1M
Available since September for CICS/TS 2.2

CICS/TS 2.3 announced 28th October


Planned availability December 19, 2003

Price
There is no charge for the IBM SOAP for CICS feature

Nov 5th 2003 © Dacworks limited Page 4


DACWORKS

Simple Object Access Protocol


Provides a firewall-friendly way for exchanging XML with CICS
Transports are provided over Hypertext Transfer Protocol (HTTP) and
WebSphere MQ
Includes support for Secure Sockets Layer (SSL) via HTTPS
Both inbound and outbound function is provided
The CICS implementation supports SOAP 1.1.
Allows Microsoft and distributed client community direct access to CICS in a
format they understand - XML

CICS
Servers
Nov 5th 2003 © Dacworks limited Page 5
DACWORKS

IBM SOAP for CICS feature


Allows CICS/TS 2.2 to be an HTTP client as well as an HTTP server
IBM SOAP for CICS
Permits existing CICS COMMAREA-based applications to be driven via
XML-formatted SOAP messages
Can also be used for new XML-aware applications driven via SOAP
messages
Enables CICS applications to issue outbound SOAP messages targeted via
SOAP or XML messaging to remote applications

Client Soap Soap over Server Soap


Request http(s) Response

Nov 5th 2003 © Dacworks limited Page 6


DACWORKS

SOAP Request example


<?xml version="1.0" encoding="utf-8" ?>
<soap:Envelope
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<GetUKLocationByTown xmlns="http://www.webserviceX.NET">
<Town>Steyning</Town>
</GetUKLocationByTown>
</soap:Body>
</soap:Envelope>

Nov 5th 2003 © Dacworks limited Page 7


DACWORKS

SOAP Response example


<?xml version="1.0" encoding="utf-8" ?>
- <soap:Envelope
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
- <soap:Body>
- <GetUKLocationByTownResponse
xmlns="http://www.webserviceX.NET">
<GetUKLocationByTownResult>
<NewDataSet> <Table> <Town>Steyning</Town>
<County>West Sussex</County> <PostCode>BN44</PostCode>
</Table> </NewDataSet></GetUKLocationByTownResult>
</GetUKLocationByTownResponse>
</soap:Body>
</soap:Envelope>
Nov 5th 2003 © Dacworks limited Page 8
DACWORKS

IBM SOAP for CICS feature inbound


When a SOAP message arrives
The SOAP request needs to be parsed and passed to a CICS application
program somewhere in the CICSplex
A SOAP response or SOAP fault message is returned to the client
Use IBM SOAP for CICS feature provided utilities, or roll your own

XML Input Message


Parse Mapping
External Application
Client in CICSplex
Message Output
Message
Generator Mapping
CICS SOAP SERVER

Nov 5th 2003 © Dacworks limited Page 9


DACWORKS

IBM SOAP for CICS feature inbound


Which clients can work with CICS?
Any external client that understands SOAP can communicate with CICS
No need for gateways or environments doing TCPIP-SNA protocol conversion
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-
instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<request1 command="view">
<account>
<department>1</department>
<employeeNumber>00001</employeeNumber>
</account>
</request1>
</soap:Body>
</soap:Envelope> SOAP request
External CICS
Client SOAP
SERVER

<items command="view” result="success">


<record>
<department>1</department>
<employeeNumber>00001</employeeNumber>
<name>DAVID CLANCY</name>
<address1>DACWORKS</address1>
<address2>STEYNING</address2>
<address3>ENGLAND</address3>
<phone>12345678</phone>
<salary>12345600</salary>
<startDate>01082003</startDate>
<timeStamp><![CDATA[003243164395910C]]></timeStamp>
<remarks>www.dacworks.co.uk</remarks>
</record>
</items> SOAP response
Nov 5th 2003 © Dacworks limited Page 10
DACWORKS

IBM SOAP for CICS feature outbound


Program DFHWBCLI
This a utility program invoked via EXEC CICS LINK to provide outbound
HTTP(S) support
DFHWBCLI may also be used independently of SOAP for CICS

Input to DFHWBCLI
URL of the destination server External
URL of any proxy server DFHWBCLI Web
Method
HTTP request headers Server
Optional CICS Document token

Input to DFHWBCLI includes the SOAP request Output includes SOAP Response
- <GetUKLocationByTownResponse
xmlns="http://www.webserviceX.NET">
<?xml version="1.0" encoding="utf-8" ?> <soap:Envelope <GetUKLocationByTownResult>
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" <NewDataSet>
xmlns:xsd="http://www.w3.org/2001/XMLSchema" <Table>
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <Town>Steyning</Town>
<soap:Body> <County>West Sussex</County>
<GetUKLocationByTown xmlns="http://www.webserviceX.NET"> <PostCode>BN44</PostCode>
<Town>Steyning</Town> </GetUKLocationByTown> </Table>
</soap:Body> </NewDataSet>
</soap:Envelope> </GetUKLocationByTownResult>
</GetUKLocationByTownResponse>

Nov 5th 2003 © Dacworks limited Page 11


DACWORKS

IBM ENTERPRISE COBOL & PL1


XML PARSER
Gives capability to transform XML documents into COBOL or PL1 data
structures

XML HTTP Message Input


SOURCE Parser Mapper WEBSPHERE
EXCI
Z/OS

Message Output
Generator Mapper
IIOP WEBSPHERE
XML ECI
DISTRIBUTED
SOURCE

CICS/TS 32k Commarea


No constraint on constraint
message size

Nov 5th 2003 © Dacworks limited Page 12


DACWORKS

Message parser
WebSphere Studio Enterprise Developer (WSED)
Provides a tool to generate converter routines from COBOL copybooks
Enterprise COBOL V3 and Enterprise PL/I V3
Support a highly efficient event-based parser to roll your own mappings
<items command="update" result="success"> Start of document: length=00000450 characters.
<record> Start element tag: <items>
<department>1</department>
Attribute name: <command>
<employeeNumber>00001</employeeNumber>
<name>DAVID CLANCY</name> Attribute value characters: <update>
<address1>DACWORKS</address1> Attribute name: <result>
<address2>STEYNING</address2> Attribute value characters: <success>
<address3>ENGLAND</address3> Content characters: < >
<phone>12345678</phone>
Start element tag: <record>
<salary>12345600</ salary>
<startDate>01082003</startDate> Start element tag: <department>
<timeStamp><![CDATA[003243164395910C]]></timeStamp> Content characters: <1>
<remarks>www.dacworks.co.uk</remarks> End element tag: <department>
</record> Start element tag: <employeeNumber>
</items>
...

Nov 5th 2003 © Dacworks limited Page 13


DACWORKS

IBM SOAP for CICS feature


SOAP messages are transmitted in unicode (UTF-8)
Nearest supported CICS codepage is iso-8859-1
Message needs to be translated to EBCDIC host page
Problems with x'BA' and x'BB' a.k.a. '[' and ']'
Solution
Use Enterprise compilers codepage conversion services
To process UTF-8 data, first convert the data to UTF-16 in a national data item
After processing the national data, convert it back to UTF-8 for output

Client Soap Soap over Server Soap


Request http(s) Response

Nov 5th 2003 © Dacworks limited Page 14


DACWORKS

COBOL UNICODE SUPPORT


National data items
01 davids-national-data PIC N(32000) usage national.
Enterprise COBOL uses UTF-16 for the national data type
Coded character set identifier (CCSID) 1200
SOAP requires UTF-8
Coded character set identifier (CCSID) 1208
National-of: converting UTF-8 TO UTF-16
move function national-of(davids-utf8-data, 1208)
to davids-national-data
Display-of: converting to a chosen codepage
move function display-of(davids-national-data, 1140)
to davids-ebcdic-data

Nov 5th 2003 © Dacworks limited Page 15


DACWORKS

Code pages supporting the €uro


Nearest
Euro
Pre-euro Description
CCSID
CCSID
923 819 ISO/IEC 8859 part 15.
924 500 and EBCDIC codepage with same character set as 923.
1047
1140 37 EBCDIC USA, Canada, Netherlands, Portugal, Brazil,
Australia, New Zealand
1141 273 EBCDIC Austria, Germany
1142 277 EBCDIC Denmark, Norway
1143 278 EBCDIC Finland, Sweden
1144 280 EBCDIC Italy
1145 284 EBCDIC Spain, Latin America (Spanish)
1146 285 EBCDIC UK
1147 297 EBCDIC France
1148 285 EBCDIC Belgium, Canada, Switzerland
1149 871 EBCDIC Iceland

Some z/OS configuration is required for compilers to work with UNICODE


Nov 5th 2003 © Dacworks limited Page 16
DACWORKS

Passing data between CICS programs


Traditional commarea 32K
Showing its age but may be required for existing CICS applications
The SOAP for CICS feature
Uses functions provided by CICS Business Transaction Services (CICS/TS 1.3)
Sysplex enabled

CBTS CONTAINERS
Output Includes SOAP Response
New or modified
- <GetUKLocationByTownResponse STATE DATA
xmlns="http://www.webserviceX.NET">
CICS application
<GetUKLocationByTownResult>
<NewDataSet>
<Table>
<Town>Steyning</Town>
XML Mapping
<County>West Sussex</County> Parse CICS
<PostCode>BN44</PostCode> COMMAREA Commarea based
</Table> 32K CICS application
</NewDataSet>
</GetUKLocationByTownResult>
</GetUKLocationByTownResponse>

Nov 5th 2003 © Dacworks limited Page 17


DACWORKS

Message generation
CICS Web Support Document commands (CICS/TS 1.3)
EXEC CICS DOCUMENT CREATE
EXEC CICS DOCUMENT INSERT
EXEC CICS DOCUMENT SET
EXEC CICS DOCUMENT RETRIEVE

CBTS CONTAINERS CBTS CONTAINERS


New or modified
STATE DATA CICS application STATE DATA

Message
Mapping generation
CICS CICS
COMMAREA Commarea based COMMAREA
32K CICS application 32K

Nov 5th 2003 © Dacworks limited Page 18


DACWORKS

Message generation - 1
DOCUMENT CREATE
Creates a document buffer up to 1Gb in size
Could be html, xml, wml, soap, gif, jpg - i.e. any MIME type
Can be sent with CWS WEB SEND command over http(s) or RETRIEVED for
alternative transmission

EXEC CICS
DOCUMENT CREATE
DOCTOKEN(WS-TOKEN)
DOCSIZE(WS-RETRIEVE-LENGTH)
TEMPLATE('DACP04')
SYMBOLLIST(WS-SYMBOLS)
LISTLENGTH(LENGTH OF WS-SYMBOLS)
END-EXEC

Nov 5th 2003 © Dacworks limited Page 19


DACWORKS

Message generation - 2
DOCUMENT INSERT
Allows the document to be composed from multiple templates
Templates simplify building dynamic content - alternative to jsp
CICS templates can be built with any editor, WSED, FRONTPAGE etc.

EXEC CICS
DOCUMENT INSERT
DOCTOKEN(WS-TOKEN)
DOCSIZE(WS-RETRIEVE-LENGTH)
TEMPLATE('DACPREC')
END-EXEC.

<BODY> <jsp:useBean id="md" type="my.package.MyData”


scope="request"/>
Userid: &Userid; <BODY>
or
Userid <!--#echo var=Userid--> Userid: <%=md.getUserid() %>

Nov 5th 2003 © Dacworks limited Page 20


DACWORKS

Message generation - 3
DOCUMENT SET
Allows for symbol substitution in document templates
Symbol values may be fixed or variable length
Symbols may be updated individually or in groups (symbol lists)

MOVE 'Userid’ TO WS-SYMBOL-NAME

EXEC CICS DOCUMENT SET DOCTOKEN(WS-TOKEN)


SYMBOL (WS-SYMBOL-NAME)
VALUE (TRANSACTION-USERID)
LENGTH (USERID-LENGTH)
END-EXEC

Nov 5th 2003 © Dacworks limited Page 21


DACWORKS

Message generation - 4
DOCUMENT RETRIEVE (optional)
Allows access to document buffer for alternative transmission from CICS
The message can be delivered by any CICS mechanism: commarea, transient
data queue, WebSphere MQ, IIOP or HTTP(S)

<?xml version="1.0" encoding="utf-8"?>


<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-
instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
EXEC CICS <items command="view” result="success">
DOCUMENT RETRIEVE <record>
<department>1</department>
DOCTOKEN(WS-TOKEN) <employeeNumber>00001</employeeNumber>
INTO(LS-RETRIEVE-DOC1) <name>DAVID CLANCY</name>
LENGTH(WS-RETRIEVE-SAVE) <address1>DACWORKS</address1> SOAP response
MAXLENGTH(WS-DOCSIZE-LENGTH) <address2>STEYNING</address2>
<address3>ENGLAND</address3>
END-EXEC <phone>12345678</phone>
<salary>12345600</salary>
<startDate>01082003</startDate>
<timeStamp><![CDATA[003243164395910C]]></timeStamp>
<remarks>www.dacworks.co.uk</remarks>
</record>
</items>
</soap:Body>
</soap:Envelope>

Nov 5th 2003 © Dacworks limited Page 22


DACWORKS

CICS/TS 2.3 JCICS Enhancements


JCICS now supports the DOCUMENT API
Allows Java application programmers to access CICS Web support data and
develop CICS Web applications without using servlets and JSPs.

Methods EXEC CICS Commands

create() DOCUMENT CREATE

insert() DOCUMENT INSERT

setSymbolList() DOCUMENT SET

retrieve() DOCUMENT RETRIEVE

Nov 5th 2003 © Dacworks limited Page 23


DACWORKS

Summary
IBM SOAP for CICS feature
Provides a firewall-friendly way for exchanging XML with CICS
Message parsing, mapping and message generation run under CICS
Supports very large messages
UTF-8 to host codepage conversion now possible with Enterprise compilers
Allows Microsoft and distributed client community direct access to CICS in a
format they understand - XML/SOAP

CICS
Servers
Nov 5th 2003 © Dacworks limited Page 24
DACWORKS

Further information
information
IBM SOAP for CICS feature
http://www.ibm.com/software/htp/cics/soap/
CICS/TS 2.3 Announcement
http://www-3.ibm.com/software/htp/cics/tserver/v23/
Enterprise COBOL
http://www-3.ibm.com/software/ad/cobol/zos/library/
XML 1.1 specification
http://www.w3.org/TR/xml11/
SOAP 1.1 specification
http://www.w3.org/TR/SOAP/
CICS SOAP and JCICS workshops
http://www.dacworks.co.uk

Nov 5th 2003 © Dacworks limited Page 25

Potrebbero piacerti anche