Service Oriented Architectures and Web Services: Introduction

Service Oriented Architectures and Web Services: Introduction. 1

Jazz and Classical CICS programming. 1

Jazz and Service Oriented Architectures. 2

The Structure of SOAs. 2

Binding and Pipelines:  Setting Up Your System for Web Services. 4

1.    Check That Your CICS System Enables Web Services. 4

2.    Configure Jazz for Web Services. 5

3.    Testing Your First Web Service Provider 9

4.    Testing a Web Requester Program.. 9


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.


In preparing this section of the Jazz Users’ Guide 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

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 character 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: -

Jazz and Service Oriented Architectures

In contrast to a 3270-type screen a web service is an “Intelligent object”, with its own logic. One program – the requester – invokes a web service which responds in some way. The response may be simply to calculate a result and send it back, and there may be no display at all. For example there is a test service, SOATest1, provided on the JazzSoftware web site.  We send some text, 'Robert', to SOATest1 which sends back a response 'SOATest1. Hello Robert. The NZ date/time is 27/02/2014 2:45:21 p.m.'. Of course a web service may be much more complex than SOATest1, which is little more than a “Hello World” program. The service might cause a web page or window to be displayed on the user’s computer. And the web service may undertake complex processing involving several further layers of communication whether or not it displays anything.


Communicating with a web service is like CICS communication with another program via INVOKE. INVOKE Prog2(…); invoked another CICS program; INVOKE JZTst-SOATest1(…);  invokes an SOA object. There is little difference in the syntax of the INVOKE statement; it is the interface definitions of Prog2 and SOATest1 that tell Jazz what sort of object is being invoked, and how to interact with it.


Jazz programs can not only invoke web services, they can provide them, being like SOATest1 in the example above. To write such a program we start with a PROGRAM statement like


The message format is defined (in this example) by the COMMAREA, named “GetTimC”.  If Jazz can’t find a definition for this then a dialog will follow in which you define this interface. If the interface definition already exists then you can edit it.


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. It is highly unlikely that you’d 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 any way they like.  They don’t have to follow the rules of 3270 screen formats, and formats need not be closely related to the display, if any, produced by the web service client.  And since web pages and windows have their own logic they may engage in a dialog with the user, 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

Don’t be too concerned if you find this material dauntingly technical. All you need at this stage is a general appreciation of the way that an SOA works, and the details will become a lot clearer (and simpler) as you start developing service requests and services with Jazz.


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 Broker (sometimes called a “Service Registry”) makes the Web Service interface and implementation access information available to any requester.

3.                   A Service Requestor can discover this interface information and use it to request the service.


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 zOS 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.


So 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 server are required.

2.                   Self-describing. Web Services Description Language (WDSL) provides all the information that a provider needs to implement a web service, and a requester needs to invoke it.

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 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 Australia but you want a page from the U.S.A, so the Australian DNS may have to request information from the US DNS. Through this process the requester finds out where to send the request.

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, and may be binary code rather than readable text. Also they might be encrypted (web pages can be encrypted too).


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: SOAP is far from simple.  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 SOAP messages.  REST messages will be added when this feature’s development is supported by users.

Binding and Pipelines:  Setting Up Your System for Web Services.

With a classical CICS program Jazz generated a screen layout, submitting a job to compile the “physical map” and generating the “symbolic map” describing the fields in the screen directly into the COBOL program.  A web service program also needs descriptions of the message formats, but these descriptions have to be available to be discovered by any program that needs them. 


For example, program GetTim (see chapter JazzUGSOA2) provides a web service that, given “Robert” as an input value, will return “Hello Robert.  The time in Dallas is ….”.   When we develop a Jazz web service provider  program like GetTim the input and output message formats are defined through a dialog and then when we click [Process] steps are included in the submitted job to create the objects that enable an external service to discover what it needs to know to invoke the service.  Two objects are necessary, a binding file and WSDL.   The binding file tells CICS how to process messages through the pipeline so that data is converted to and from the message formats into the form that our program needs, and WSDL describes what the external message looks like.


Similarly when we develop a program like WST1 (see chapter JazzUGSOA4) that invokes (requests) a web service a discovery dialog finds the web service and its message formats, and submits a job to create the binding file that allows the service request to find its way from our program to the target service, and for the reply to find its way back.


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.  However the first time that this is done can be a bit difficult, and you’ll need to work through this with your system programmer.

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 here to learn about configuration in general – the use of symbolic parameters, what is JZL, etc.


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. 


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.


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.


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.  The Group value is appended to this, so with the Configuration values shown above the URI for GettimB is


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   You’d define the domain as “Megabank.webservices”.  You don’t need to include www., and the service can be reached by either or


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. 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.


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: -





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: -


If this is needed, write this JCL statement here.  If it is not needed, leave Proclib blank.


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=''''


















//COPYWS1 EXEC PGM=BPXBATCH,REGION=0M,PARM='SH cp @hfs/@program.wsdl @hfs/wspickup/@program.wsdl'





//COPYWS2 EXEC PGM=BPXBATCH,REGION=0M,PARM='SH cp @hfs/@program.wsbind @hfs/wspickup/@program.wsbind'






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.


DEFINE Wrk DATA(Now CHAR(21)); = $Now;

OGettimb.result = 'Hello ' && && '. the time in Dallas is now ' &&;


Combining this with the configuration form above Jazz produces this JCL: -












//        DD





//*** CREATE WSBIND AND WSDL from program information

//    SET QT=''''


















//COPYWS1 EXEC PGM=BPXBATCH,REGION=0M,PARM='SH cp /u/manajazz/Provider/X

//             GettimB.wsdl /u/manajazz/Provider/wspickup/GettimB.wsdl'





//COPYWS2 EXEC PGM=BPXBATCH,REGION=0M,PARM='SH cp /u/manajazz/Provider/X

//             GettimB.wsbind /u/manajazz/Provider/wspickup/GettimB.wsbX

//             ind'






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.


//    SET QT=''''                














//COPYWS1 EXEC PGM=BPXBATCH,REGION=0M,PARM='SH cp @hfs/@program.wsdl @hfs/wspickup/@program.wsdl'





//COPYWS2 EXEC PGM=BPXBATCH,REGION=0M,PARM='SH cp @hfs/@program.wsbind @hfs/wspickup/@program.wsbind'






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  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.