Service
Oriented Architectures and Web Services: Introduction
Service
Oriented Architectures and Web Services: Introduction
Jazz
and Classical CICS programming
Service
Oriented Architectures
Setting
Up Your z/OS System for Web Services
1. Check That Your CICS System Enables Web
Services
2. Configure Jazz for Web Services
3. Testing Your First Web Service Provider
4. Testing a Web Requester Program
Prerequisite reading: Introduction to Jazz, Jazz On Line Programming, Introduction, Jazz On Line Programming, Part2. Updating Records
In this chapter we introduce the standards and basic principles of Service Oriented Architecture (SOA). You should read this before continuing with either the next chapter, showing you how to write a program that provides a web service, or the following chapter showing you how to write a program that invokes a service.
This series of Users’ Guide pages was written assuming that you were developing CICS Web Services with z/OS. If you are using Micro Focus software such as Micro Focus Enterprise Developer ™ then you should read Web Services with Jazz and Micro Focus. The sections here down to (including) “Binding and Pipelines” will be useful, but “Setting up your z/OS system for Web Services” is specific to z/OS.
In preparing this section of the Jazz Users’ Guides the IBM Redbook “Application Development for CICS Web Services”, SG24-7126-01, was extensively consulted. You might like to download this and read it for further information.
Jazz
and Classical CICS programming
Earlier chapters have dealt with “Classical CICS programming”, in which a program interacts with a 3270-type screen, or another CICS program. Such screen communication looks like this.
Here the screen is responsible for the display layout but nothing else. Apart from a field’s display characteristics all the logic of what to do with the data in this field is in the program, not the screen. Even simple actions like “If code is “N” display the New Customer Panel, else hide this section of the screen” requires the screen to be processed by a CICS program which was written in Jazz (or COBOL, PL/I, etc).
We created two kinds of objects: -
1
Programs. CICS programs start with a statement
like
PROGRAM CICS3
CICS INSCREEN(CICS3S) TRANSID(TRN3) EXIT(MENU1);
We then write Jazz logic for program CICS3 to specify what the program should do when CICS starts it up, either because some input from the screen CICS3S was received, or because the transaction id “TRN3” was entered.
The program can send output back to this screen with
SEND CICS3S(data list) …
or to another screen
SEND SCRN2(data list) …
2 Screens. Using the [Screen] button we can create a 3270-type screen, placing fields and constants on it wherever we like within the 80*24 characters space allowed. Because Jazz knows that screen CICS3S is “3270-type” appropriate communication structures and commands are created within program CICS3. A few table entries were set up, for example so that transaction code TRN3 starts program CICS3.
A CICS program can also communicate with another CICS program: -
Service
Oriented Architectures
The differences between a CICS/3270 program and a CICS/WEBSERVICE program are profound.
Firstly, the communication structures are very different. As you will have seen in JazzUGOnLine1.htm#ReferringToScreenData 3270 screens have a particular communication format that is passed between the screen and the program. You will not use this format for communicating with a “Web Screen”. Instead, the web service program (COBOL? Java? .NET?) defines the formats of its input and output messages in COBOL or Java or .NET any way they like.
Secondly, the program requesting a response is not just a screen that does nothing but display the data. It has its own logic, it may get further data from local databases and functions, invoke further web services, getting more information and reacting in various ways that the original requestor has no knowledge of. The CICS program has to be prepared for a long wait for a response. It may never come.
Before we finish this chapter and go to one of the following chapters which show you how to provide or invoke a web service we start by looking at the structure of SOAs and the way that they work.
The
Structure of SOAs
A Service Oriented Architecture has three components: -
1. A Service Provider provides a “Web Service”, so that if it is properly requested to provide this service it can do so. The service provider will publish the interface that it uses, so that other programs will know how to request its services, and how to interpret the responses.
2. A Service Requestor can discover this interface information and use it to request the service.
3. A Service Broker (sometimes called a “Service Registry”) may make the Web Service interface and implementation access information available to any requester.
The whole process can be represented like this: -
All three components can be on different computers with different technology, or they may be simply different aspects of the same system on one computer. Each component can act as the other two: for example a service provider may require information from another service, so it acts as a service requester while servicing its request. One of the beauties of the SOA approach is that the service requester doesn’t care, it only needs to be concerned with the interface and access rules. Thus the service requestor might be a CICS Jazz (=COBOL) program running on a z/OS mainframe, but the service provider might be Java running under Linux. Or the Service Requester might be a web page written in ASP.Net and the provider might be a CICS COBOL program accessing a DB2 database. The participants are loosely coupled, increasing flexibility and making it easier to introduce new interfaces and services.
Service Oriented Architectures have been used for many years in several forms, using various distributed computing technologies such as CORBA or messaging middleware, but in the absence of agreed standards and of sufficiently broad implementations of the messaging middleware their effectiveness has been limited. Web Services technology is the ideal choice for implementing an SOA as it is based on standards that are widely supported, and is platform and technology neutral.
What is a Web Service?
A web service may be anything from a simple Request/Reply to a complex business process involving many interactions and complex processing. A web service is: -
1. Self contained. On the client side a programming language with XML and HTTP client support is enough. On the server side an HTTP server (software that can serve web pages on request) and a SOAP or REST server are required.
2. Self-describing. A description in JSON (JavaScript Object Notation) or WSDL (Web Services Description Language) provides all the information that a provider needs to implement a web service, and a requester needs to invoke it. WSDL is an older standard, now largely replaced by JSON.
3. Published, Located, and invoked across the Web. Web services use established Internet Standards such as HTTP and TCP/IP, making use of existing infrastructure.
4. Modular. Simple web services can be combined into more complex services.
5. Language Independent and Interoperable. The client and server may be implemented in different languages, on different computers.
6. Inherently open and standards-based. XML and HTTP are the major technical foundations for Web services, and much of the technology has been build using open-source projects. Vendor independence is a realistic goal.
7. Loosely coupled. Web services require simpler coordination than traditional application design, making reconfiguration easier and more flexible.
8. Encapsulated. Requesters (service consumers) need to know the interfaces, but know nothing about the implementation details. There is no graphical user interface.
Think of a web page, but one designed to return information to another program rather than to a human reader. Two things happen when you enter the URL of a web page such as http://www.jazzsoftware.co.nz/ into a browser (Internet Explorer?) and click <enter>, or you click on a link: -
1
The browser sends the request to a “Domain Name
Server” (DNS), which is a server containing a list of domain names and their
corresponding IP addresses. It is possible that this DNS has to send requests
to other DNS services to find the IP address hosting this site: for example
you’re in
2 The request is then sent to the identified IP address, where a particular page from a folder is located and returned. The text returned to the browser will be a stream of characters mixing HTML codes like <b>… </b> with data. HTML means “HyperText Markup Language”, and is a standard way of describing the data’s format (for example <b> means “Bold”), and where to find objects. However it doesn’t describe the meaning of the data, so it would be very difficult for a program to interpret the data: for example, that the string of characters just after the text “Account Number” could be used to look up a value of CustID in file CustF.
A web service behaves the same way, but the messages between the requester and server aren’t designed primarily to be read by a human. Also they might be encrypted (web pages can be encrypted too).
Web Service Standards
TCP/IP and HTTP 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 more additional standards that are important,
· XML – Extensible Markup Language
· UDDI – Universal Description, Discovery, and Integration
For SOAP messages
· SOAP – Simple Object Access Protocol
· WSDL – Web Services Description Language
For REST messages
· REST – Representational State Transfer
· JSON – Javascript Object Notation
All this is very complex. Fortunately you won’t need to know about these standards in any depth as Jazz will take care of all the details for you.
For more information about these standards you can click here to read more if you want to, but you don’t need to.
Jazz currently supports both SOAP and REST messages, but active development with SOAP has ceased and REST support is now more advanced. You must use REST(JSON) to create interfaces and Bridge applications.
Binding
and Pipelines.
We develop the programs in the languages that are suitable for our task and experience. CICS Web Services are often developed in COBOL, and client programs that request these services are often developed with Java. The point of web services is that these two programs can communicate, even though the COBOL program doesn’t know anything about Java, and the Java program doesn’t know anything about COBOL. To enable this to happen, the Java request is turned into a JSON input message which is sent to the REST server where a pipeline (a sequence of programs) converts the JSON to COBOL, and passes this to our COBOL web service. This COBOL program does its thing and returns its output as a COBOL data structure which goes back through the pipeline with the reverse conversion so that JSON is sent back to the requestor. The whole process is shown in this diagram: -
We need to set our mainframe system up so that it can handle web services, both as provider and requestor, and we need to configure Jazz so that it can create these web services. You’ll only need to do this once for your project, and then you and other project team members can simply use this set-up. The first time that this is done can be a bit difficult, and you’ll need to work through this with your system programmer, after that you and other application programmers can focus on the Jazz (COBOL) logic.
Setting
Up Your z/OS System for Web Services
If you’re using Micro Focus software such as Micro Focus Enterprise Developer™ the following material doesn’t apply. Instead, read Web Services with Jazz and Micro Focus.
1. Check That Your CICS System Enables Web
Services
Your system programmer needs to confirm that your CICS
system is set up for web services. See Configuring
your CICS system for web services
Essential features are: -
1.
Language Environment® support for PL/I needs to
be installed. Although we’re not going
to use PL/I ourselves, some of the IBM support programs that we’ll be using in
the background were written in PL/I.
2. Activate z/OS® Support for Unicode.
2. Configure Jazz for Web Services
Click the [Configure] button, and then the z/OS tab: -
Note the section “Web Services”. Here we define the HFS, the JZL templates that are used for web service jobs, and other information that will be needed.
HFS
The HFS – Heirachical File System – is the part of the z/OS UNIX file system that is used for our web services. The UNIX file system contains some folders (directories) that users can update, and some that they cannot: the HFS must be updateable. We’ll name our HFS within the “/u” folder. My normal practice is to name this as “/u/@lcgroup/@mode”, picking up the second part of the ISPF file naming hierarchy, so that for @Group = “MANAJAZZ” the HFS will be “u/manajazz/… There will then be two subfolders within this for the two possible values @mode=“Provider” and @mode=”Requester”. Within these folders there need to be further subfolders, /shelf and /pickup. Click [Check HFS] to ensure that all these folders exist, or to create them as necessary.
Jazz will create objects for each service in the appropriate folders. For example if one of our programs requests service SOATst, Jazz will create objects /u/manajazz/Requester/SOATst.wsdl and “/u/manajazz/Requester/SOATst.wsbind”.
[Check HFS]
Checks (and creates if necessary, subject to a dialog), the folders defined as HFS.
Ports
Find out from your system programmer the port numbers that you should use to send and receive HTTP and HTTPS messages. The values 80 and 443 are the z/OS system defaults, but are probably not permitted for general use. Values above 1000 may be used, provided that they are not being used for any other purposes. The values shown above, 9014 and 9015 are entirely arbitrary, and HTTPS access has not yet been tested.
Domain
If this is blank Jazz creates URI’s using the IP number from the Job Submission section, and the port number for HTTP, i.e. 192.86.32.59:9014. The Group value is appended to this, so with the Configuration values shown above the URI for GettimB is http://192.86.32.59:9014/manajazz/Provider/GettimB
It is
planned (not yet implemented) that you can give a domain name so that external
programs requesting your service know what URL to give, rather than using the
IP. For example, if you are providing a
web service called “Accounts” at Megabank you might want external users to
request the service from http://www.megabank.com/webservices/Accounts.wsdl. You’d define the domain as “Megabank.webservices”.
You don’t need to include www., and the
service can be reached by either http://www.megabank.com/webservices/Accounts.wsdl
or http://megabank.com/webservices/Accounts.wsdl
We need to get our system programmer to set up our z/OS system so that web requests to a name based on the value that we entered in the Domain textbox, e.g. www.megabank.com/webservices/GettimB are resolved to our program GettimB. The domain will need to be registered with a domain name registry so that it can be discovered through the internet.
Proclib
Some examples below have been retained from earlier development when SOAP (using WSDL) was the only approach available. For REST (JSON) web services there are JZL templates for SOAP and REST, but the REST templates have not been validated as all our testing has been with Micro Focus Enterprise Developer. Where the examples refer to names like DFHWS2LS, the REST equivalent will be DFHJS2LS, e.g. “WS” becomes “JS”.
Jobs running the CICS web service assistant programs use JCL that executes a procedure. For example here is some JCL from a job running DFHWS2LS to create record definitions and a .wsbind file from WSDL: -
//IBMUSERI
JOB
,CLASS=A,MSGCLASS=H,NOTIFY=&SYSUID,COND=(8,LT)
….
//DFHWS2LS
EXEC DFHWS2LS,REGION=0M,
It might be necessary to specify a JCLLIB in order for the procedure DFHWS2LS to be resolved correctly. For example, in my case I need this statement to appear in the JCL right after the JOB statement: -
//JOBPROC
JCLLIB ORDER=DFH510.SVSC.CUSTOM.INSTALL
If this is needed, write this JCL statement here. If it is not needed, leave Proclib blank.
Provider
For a service provider the COBOL compile is followed by a step based on a JZL template that will run the CICS web service assistant program DFHLS2WS to create the WSDL and binding files. In this textbox you name the JZL template. A default provider template named JZWSProv is provided. You should check this template, and if necessary edit it to meet your requirements. It might be necessary to have different templates for different projects.
Here is the default JZWSProv: -
//***
CREATE WSBIND AND WSDL from program information
// SET QT=''''
//DFHLS2WS
EXEC DFHLS2WS,REGION=0M,
// TMPFILE=&QT.&SYSUID.&QT
//INPUT.SYSUT1
DD *
LOGFILE=@HFS/@Program.log
PDSLIB=//@Copy
REQMEM=@Reqmem
RESPMEM=@Respmem
OPERATION-NAME=@Program
LANG=COBOL
MAPPING-LEVEL=3.0
PGMNAME=@Program
@Pgmint
@Contid
WSDL=@hfs/@Program.wsdl
WSBIND=@hfs/@Program.wsbind
URI=@URIProv
/*
//COPYWS1
EXEC PGM=BPXBATCH,REGION=0M,PARM='SH cp @hfs/@program.wsdl
@hfs/wspickup/@program.wsdl'
//STDOUT
DD PATH='/tmp/@userid.stdout',PATHOPTS=(OWRONLY,OCREAT),
//
PATHMODE=SIRWXU
//STDERR DD
PATH='/tmp/@userid.stderr',PATHOPTS=(OWRONLY,OCREAT),
// PATHMODE=SIRWXU
//COPYWS2
EXEC PGM=BPXBATCH,REGION=0M,PARM='SH cp @hfs/@program.wsbind
@hfs/wspickup/@program.wsbind'
//STDOUT
DD PATH='/tmp/@userid.stdout',PATHOPTS=(OWRONLY,OCREAT),
//
PATHMODE=SIRWXU
//STDERR DD
PATH='/tmp/@userid.stderr',PATHOPTS=(OWRONLY,OCREAT),
// PATHMODE=SIRWXU
The @ parameters are resolved by Jazz using values that mostly come from the configuration form. Parameters @Reqmem, @Respmem, @Program, @Pgmint and @Contid are given values when Jazz processes the program. Parameter @mode will have value “Requester”. For example, here is a web services provider program GettimeB: -
*# Last Updated by IBMUSER at 15/04/2015 4:14:50 p.m.
PROGRAM
GettimB WEBSERVICE MySvce CONTAINER JZContainer;
DEFINE
Wrk DATA(Now CHAR(21));
Wrk.now
= $Now;
OGettimb.result
= 'Hello ' && IGettimb.name
&& '. the
time in
REPLY;
Combining this with the configuration form above Jazz produces this JCL: -
//IBMUSERV
JOB
,CLASS=A,MSGCLASS=H,NOTIFY=&SYSUID,COND=(8,LT)
//JOBPROC
JCLLIB ORDER=DFH510.SVSC.CUSTOM.INSTALL
//***
COMPILE CICS PROGRAM or SUBPROGRAM
// SET MEMBER=GETTIMB
// SET SOURCE=IBMUSER.MANAJAZZ.SRCLIB
// SET COPYLIB=IBMUSER.MANAJAZZ.CPYLIB
//COMPILE EXEC
IGYWCL,PARM.COBOL=CICS
//COBOL.STEPLIB DD
DSN=DFH510.CICS.SDFHLOAD,DISP=SHR
//COBOL.SYSLIB DD DSN=DFH510.CICS.ADFHCOB,DISP=SHR
//COBOL.SYSIN DD
DSN=IBMUSER.MANAJAZZ.SRCLIB(GETTIMB),DISP=SHR
//LKED.SYSLIB DD
// DD
// DD
DSN=IBMUSER.MANAJAZZ.LOADCICS,DISP=SHR
// DD DSN=DFH510.CICS.SDFHLOAD,DISP=SHR
//LKED.SYSLMOD DD DSN=IBMUSER.MANAJAZZ.LOADCICS(GETTIMB),
// UNIT=,SPACE=,DISP=SHR
//***
CREATE WSBIND AND WSDL from program information
// SET QT=''''
//DFHLS2WS
EXEC DFHLS2WS,REGION=0M,
// TMPFILE=&QT.&SYSUID.&QT
//INPUT.SYSUT1
DD *
LOGFILE=/u/manajazz/Provider/GettimB.log
PDSLIB=//IBMUSER.MANAJAZZ.CPYLIB
REQMEM=IGETTIMB
RESPMEM=OGETTIMB
OPERATION-NAME=GettimB
LANG=COBOL
MAPPING-LEVEL=3.0
PGMNAME=GettimB
PGMINT=CHANNEL
CONTID=JZCONTAINER
WSDL=/u/manajazz/Provider/GettimB.wsdl
WSBIND=/u/manajazz/Provider/GettimB.wsbind
URI=http://192.86.32.59:9014/MNJZPROV/GettimB
/*
//COPYWS1
EXEC PGM=BPXBATCH,REGION=0M,PARM='SH cp /u/manajazz/Provider/X
// GettimB.wsdl
/u/manajazz/Provider/wspickup/GettimB.wsdl'
//STDOUT
DD PATH='/tmp/IBMUSER.stdout',PATHOPTS=(OWRONLY,OCREAT),
// PATHMODE=SIRWXU
//STDERR
DD PATH='/tmp/IBMUSER.stderr',PATHOPTS=(OWRONLY,OCREAT),
// PATHMODE=SIRWXU
//COPYWS2
EXEC PGM=BPXBATCH,REGION=0M,PARM='SH cp /u/manajazz/Provider/X
// GettimB.wsbind
/u/manajazz/Provider/wspickup/GettimB.wsbX
//
//STDOUT
DD PATH='/tmp/IBMUSER.stdout',PATHOPTS=(OWRONLY,OCREAT),
// PATHMODE=SIRWXU
//STDERR
DD PATH='/tmp/IBMUSER.stderr',PATHOPTS=(OWRONLY,OCREAT),
// PATHMODE=SIRWXU
Requester
For a service request program we will have discovered the web service through the Jazz Web Service Discovery. The first time we do this, or when we refresh a previously-discovered service, a job is submitted to run the CICS web service assistant program DFHWS2LS, based on the requestor template (JSWSReq). Here is the default template. As with the provider template, this may need to be edited for your situation, and you may need different templates for different projects.
//***
Web Service Request.
//***
CREATE WSBIND AND COBOL RECORD DEFINITION FROM WSDL
// SET QT=''''
//DFHWS2LS
EXEC DFHWS2LS,REGION=0M,
// TMPFILE=&QT.&SYSUID.&QT
//INPUT.SYSUT1
DD *
LOGFILE=@HFS/@Program.log
PDSLIB=//@Copy
REQMEM=@Reqmem
RESPMEM=@Respmem
LANG=COBOL
MAPPING-LEVEL=3.0
WSDL=@HFS/@Service.wsdl
WSBIND=@hfs/@Service.wsbind
URI=@URIReq
/*
//COPYWS1
EXEC PGM=BPXBATCH,REGION=0M,PARM='SH cp @hfs/@program.wsdl
@hfs/wspickup/@program.wsdl'
//STDOUT
DD PATH='/tmp/@userid.stdout',PATHOPTS=(OWRONLY,OCREAT),
//
PATHMODE=SIRWXU
//STDERR DD
PATH='/tmp/@userid.stderr',PATHOPTS=(OWRONLY,OCREAT),
// PATHMODE=SIRWXU
//COPYWS2
EXEC PGM=BPXBATCH,REGION=0M,PARM='SH cp @hfs/@program.wsbind
@hfs/wspickup/@program.wsbind'
//STDOUT
DD PATH='/tmp/@userid.stdout',PATHOPTS=(OWRONLY,OCREAT),
//
PATHMODE=SIRWXU
//STDERR DD
PATH='/tmp/@userid.stderr',PATHOPTS=(OWRONLY,OCREAT),
// PATHMODE=SIRWXU
Pipeline
The name of the provider pipeline must be given so that it can be put into the JCL generated for a DFHLS2WS step.
3. Testing Your First Web Service Provider
The next chapter, providing a web service, describes how to develop a very simple web service such as program GettimB. You will now need a way of invoking this web service. If you don’t already have suitable test tools, free software for testing SOAP messages can be downloaded from http://www.soapui.org/ Follow the instructions of your test tool to set up a test and invoke your service at its URI, passing it a suitable input message. If everything has been set up correctly your web service will be invoked and output returned to the test tool. See the chapter Providing Web Services for an example.
4. Testing a Web Requester Program
The chapter Invoking a Web Service shows you how to write a program that will request data from an external web service, sending a message to it with input data and then processing its output. The program illustrated there invokes SOATest1, which is a Windows version of the z/OS program that you wrote as GetTimB. Test this as described in that chapter.
When we’ve proven that we can both provide and request web services we’ll be ready to continue with real problems. If you’re like me you won’t really understand the material in this introductory chapter until you have worked through these two chapters and reached a stage where you have successfully tested a basic web service program provider program and a web service requester program, and messages are flowing between them and the outside world.