Service
Oriented Architecture Standards and CICS Web Services
Service Oriented Architecture Standards and
CICS Web Services
This
section introduces you to the standards on which Service Oriented Architectures
depend, and on the way in which CICS implements them. This is provided for your interest only, and
you won’t need to understand the material here in any depth as Jazz will take
care of all the detail for you.
SOA Standards
HTTP and TCP/IP are the basic standards on which both web pages and web services depend. For web services – data that is intended to be interpreted by a program, not a human – there are six additional standards that may be relevant to you: -
· XML – Extensible Markup Language
· SOAP – Simple Object Access Protocol
· WSDL – Web Services Description Language
· UDDI – Universal Description, Discovery, and Integration
· REST – Representational State Transfer. An alternative to SOAP
· JSON – Javascript Object Notation. An alternative to WSDL
1 Extensible Markup Language (XML). XML provides a markup language that allows you to define your own terms, giving meaning to the elements in the data stream. For example, if you write <Custid>123456</Custid> you have defined the string “123456” as an element called “Custid”. An XML element definition can contain many levels of definition: for example you might define the record layout for CustF like this: -
<CustF>
<Custid>123456</Custid>
<CustName>Robert Barnes</CustName>
<CustAddr>
<CustAddr1>13A
<CustAddr2>
<CustAddr3>
<CustCountry>
</CustAddr>
</CustF>
For more information about the XML standard, see http://www.w3.org/XML/ and http://www.w3.org/TR/2008/REC-xml-20081126/ . While the standards are much more comprehensive than I’ve shown here, all you need to take away is that
i) XML is human-readable and reasonably clear, even though its main point is that it’s easy for a program to interpret
ii) There is a standard (formal) format to XML documents
iii) Elements are named with <name>xxxx</name>. The names are whatever you like within XML rules. This implies an issue: if I have named a field CustName in XML describing one of my objects, what’s to prevent you from using CustName for something completely different in the description of one of yours? The answer: Nothing! There is a mechanism called “Name spaces” to resolve this ambiguity that we’ll come across later.
iv) Elements can contain elements. Thus Custf contains Custid, Custname, and CustAddr: CustAddr in turn contains CustAddr1, CustAddr2, CustAddr3, and CustCountry. You can see how this could correspond to a Jazz record layout or a COBOL structure.
You may have noticed that there is nothing here that describes the format of the data. What is the format of Custid – does it have to be a number? Ditto the other fields. Do we have all the fields of record CustF or are some missing? Do we have any names defined in this XML that are not actually known in our record definition? These (and other) questions are answered in the third additional standard, WSDL. But first we need a way of specifying how to get the XML message from one SOA actor to another.
2 SOAP (Simple Object Access Protocol) was designed to be a simple and extensible specification for the exchange of structured, XML-based information in a decentralized, distributed environment. As such, it represents the main means of communication between the service provider, service requestor, and service broker, the three actors in an SOA.
|
|
The SOAP specification contains three parts: - 1. An envelope that defined a framework for describing message content and processing instructions. Each SOAP message consists of an envelope with 0-N headers and one body (which carries the payload). 2. A set of encoding rules for expressing instances of application-defined data types 3. A convention for representing remote procedure calls and responses. SOAP messages can be transmitted with a variety of protocols – HTTP, SMTP, FTP, etc – but are most commonly exchanged with HTTP. It doesn’t matter what technology is used to implement the client or the server, as long as they can handle XML messages. |
Here is an example of a couple of SOAP messages[1].
First a SOAP request, which requests that a GetStockPrice service returns the price of IBM stock.
POST /InStock HTTP/1.1
Host: www.example.org
Content-Type: application/soap+xml; charset=utf-8
Content-Length: nnn
<?xml version="1.0"?>
<soap:Envelope
xmlns:soap="http://www.w3.org/2001/12/soap-envelope"
soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding">
<soap:Body
xmlns:m="http://www.example.org/stock">
<m:GetStockPrice>
<m:StockName>IBM</m:StockName>
</m:GetStockPrice>
</soap:Body>
</soap:Envelope>
The response returns the price value requested: -
HTTP/1.1 200 OK
Content-Type: application/soap+xml; charset=utf-8
Content-Length: nnn
<?xml version="1.0"?>
<soap:Envelope
xmlns:soap="http://www.w3.org/2001/12/soap-envelope"
soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding">
<soap:Body
xmlns:m="http://www.example.org/stock">
<m:GetStockPriceResponse>
<m:Price>34.5</m:Price>
</m:GetStockPriceResponse>
</soap:Body>
</soap:Envelope>
3 Web Services Description Language (WSDL)[2]. This standard describes Web services as abstract service end points that operate on messages. Because Web services are mainly implemented using SOAP and HTTP, the corresponding bindings are part of this standard. The specification for WSDL 1.1 can be found at http://www.w3.org/TR/wsdl
WSDL 2.0 enables you to separate the description of the abstract functionality offered by a service from the concrete details of a service description. It also describes extensions for MEPs, SOAP modules, and a language for describing such concrete details for SOAP1.2 and HTTP. The specification for WSDL 2.0 can be found at http://www.w3.org/TR/wsdl20
A WSDL
document is an XML document that describes a web service using these major
elements:
|
Element |
Description |
|
<types> |
A container for data type definitions used by the web
service |
|
<message> |
A typed definition of the data being communicated |
|
<portType> |
A set of operations supported by one or more endpoints |
|
<binding> |
A protocol and data format specification for a particular
port type |
Thus the main structure of a WSDL document looks like this:
<definitions>
<types>
data type definitions........
</types>
<message>
definition of the data being
communicated....
</message>
<portType>
set of operations......
</portType>
<binding>
protocol and data format
specification....
</binding>
</definitions>
A WSDL document can also contain other elements, like extension elements, and a service element that makes it possible to group together the definitions of several web services in one single WSDL document.
The <portType> element is the most important WSDL element. It describes a web service, the operations that can be performed, and the messages that are involved. The <portType> element can be compared to a function library (or a module, or a class) in a traditional programming language.
The <message> element defines the data elements of an operation. Each message can consist of one or more parts. The parts can be compared to the parameters of a function call in a traditional programming language.
The <types> element defines the data types that are used by the web service. For maximum platform neutrality, WSDL uses XML Schema syntax to define data types.
The <binding> element defines the data format and protocol for each port type.
This is a simplified fraction of a WSDL document:
<message
name="getTermRequest">
<part name="term" type="xs:string"/>
</message>
<message name="getTermResponse">
<part name="value" type="xs:string"/>
</message>
<portType name="glossaryTerms">
<operation name="getTerm">
<input message="getTermRequest"/>
<output message="getTermResponse"/>
</operation>
</portType>
In this example the <portType> element defines "glossaryTerms" as the name of a port, and "getTerm" as the name of an operation. The "getTerm" operation has an input message called "getTermRequest" and an output message called "getTermResponse". The <message> elements define the parts of each message and the associated data types.
Compared to traditional programming, glossaryTerms is a function library, "getTerm" is a function with "getTermRequest" as the input parameter, and getTermResponse as the return parameter.
Note that although all the WSDL definitions are in XML, following XML and WSDL standards, and are usually exchanged by HTTP, the actual messages might not be. The WSDL may specify that the messages are exchanged with HTTPS, FTM, MIME, FTP, etc, and the messages don’t have to be in XML format, they might even be binary. In effect the service requester and service provider use the WSDL, which is XML, to negotiate whether they can exchange data and if so how. It is quite possible that a service is available in several different forms, allowing a client to choose the most suitable for its purpose.
4
The Universal Description, Discovery, and
Integration (UDDI) standard defines a means to publish and to discover Web
services. For more information, refer to http://www.uddi.org/
and http://www.oasis-open.org/specs/index.php#wssv1.0
and http://en.wikipedia.org/wiki/Universal_Description_Discovery_and_Integration
UDDI seems a good idea that is destined
to fade into obscurity. It depended on
its success for widespread adoption, but users can get information about the
web services directly from their USL, and if they know these then they don’t
need to discover them. With users mainly
ignoring UDDI, implementers lack incentive to provide UDDI descriptive information.
5 REST and JSON
SOAP and WSDL were the first standards for web services, and when web services were first developed in MANASYS Jazz it was the only option supported within CICS without installing extra features. However REST/JSON gained popularity and now the majority of web services are deployed with these standards, and REST support is standard in current CICS. Whereas SOAP can use HTTP(S), FTM, MIME, FTP, etc, REST must use HTTP(S) – but almost all SOAP services use HTTP(S) anyway. JSON is a “lightweight” message format compared to XML, with fewer “overhead” characters identifying the fields. For example, here is a SOAP (XML) message requesting a record form service WSPG1: -
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:wsp="http://www.WSPG1.com">
<soapenv:Header/>
<soapenv:Body>
<wsp:WSPG1E>
<wsp:IWSPG1>
<wsp:JZ_Employee_Skip></wsp:JZ_Employee_Skip>
<wsp:JZ_Employee>
<wsp:EMPNO></wsp:EMPNO>
<wsp:WORKDEPT>D11</wsp:WORKDEPT>
</wsp:JZ_Employee>
</wsp:IWSPG1>
</wsp:WSPG1E>
</soapenv:Body>
</soapenv:Envelope>
Service JSPG1 is identical to WSPG1 except that it communicates with REST/JSON. Here is the same input message as above, as JSON: --
{
"JSPG1": {
"IJSPG1":
{
"JZ_Employee_Skip":
0,
"JZ_Employee":
{
"EMPNO": "",
"WORKDEPT": "D11"
}
}
}
}
These Wikipedia articles give a good introduction to REST and JSON: -
https://en.wikipedia.org/wiki/Representational_state_transfer
https://en.wikipedia.org/wiki/JSON
REST or SOAP? Your project will probably have made a choice, but if you want to understand the relative merits here are a couple of web pages from Googling “Web services rest or soap”: -
https://smartbear.com/blog/test-and-monitor/understanding-soap-and-rest-basics/
https://searchapparchitecture.techtarget.com/tip/REST-vs-SOAP-Choosing-the-best-web-service
By now your head may be spinning with all the detail of the different standards that are involved. Fortunately, while it helps to understand what is going on, MANASYS Jazz and other development tools that you use will take care of most of these details for you. Jazz doesn’t care! The only difference between the two is a choice you make in the New Web Service button, resulting in either WSDL or JSON being generated into the PROGRAM statement. Everything else is taken care of, and you don’t need to worry about the syntax of XML, WSDL, JSON, or the other standards mentioned above.
CICS
and Web Services[3]
CICS can be a provider of web services, a user of web services, or both. For example, our first CICS example was an enquiry program that looked up a VSAM file and displayed the results on a 3270 screen. A version of this program could be written that, when requested from a web page, looked up the VSAM data but instead of displaying it on a 3270 screen returned it to the web page logic (Java? ASP.NET?) for processing and display. Or a CICS program might invoke a web service to retrieve data and return it to the program.
Before all this can happen the CICS system needs to be prepared so that it can respond to valid inwards requests, and so that it can sent requests out via HTTP and process the response. Within the mainframe world of CICS we have Jazz-generated COBOL-format record layouts and COBOL programs which compile into objects that the zOS system understands. These need to be rendered as XML/SOAP/WSDL documents and transmitted across the web as web services where another program, written in Java, ASP.NET, or one of a number of other technologies can interpret the documents and act appropriately.
This diagram[4] represents the information flow when a CICS system acts as a service provider.
At the top left is a Service Requester. Think of this as a web page or app displayed on a computer (or phone etc) that, when the user requests a function like “Show price” will invoke some Business Logic from our CICS system to return the data required. The Service Requester will create a SOAP message which will sent by HTTP to our CICS system to get the answer.
At the bottom right of this diagram is the Business Logic. This is a program like those that we wrote before (see previous chapters). Perhaps it looks up a VSAM file or DB2 database to get some information. Whatever it does it will return its results through its parameters. Within Business Logic the description of the parameters and any record layouts that it wants will be expressed in the language of the logic: Jazz, COBOL, PL/I, etc. Business Logic applications may be unaware that they are being driven as Web Services.
Somehow a message has to find its way to our Business Logic, along the way being converted from XML/SOAP format to a format that our COBOL program can understand. When our Business Logic has worked out the answer the result has to undergo the reverse conversion and find its way back to the Service Requester. As the diagram above shows a moderately complex infrastructure needs to be set up correctly for this to happen. As application programmer you’ll be able to do some of this yourself with the help of Jazz and other software tools, but most of this will need to be set up for you by your CICS systems programmer. Once set up for the first message/service, adding further message types and services will be relatively easy.
The first requirement is to set up the files that relate the request and service.
1. Create an HFS[5] directory to store these files.
2. Create the WSDL and WSBind files that describe the Web Service and its bindings. One way of doing this is to run the CICS Web Services Assistant using the JCL DFHLS2WS to convert the language-specific (COBOL etc) descriptions to web service descriptions (XML). Other ways are to use Jazz or RDz: these software products create the entries directly, and have fewer limitations.
3. The CICS System Programmer should create a TCPIPSERVICE resource definition, and a PIPELINE resource definition. The WSBIND and WSDL files created in Step #2 are copied to another HFS directory (called the “pickup directory”), and the TCIPISERVICE and PIPELINE resources are installed.
4. The WDSL can then be published to users wanting to create clients to this Web Service.
As this diagram[6] shows the reverse situation when a CICS program invokes a web service is conceptually similar.
