Invoking
a Web Service.
Prerequisite reading: Service Oriented Architectures and Web Services: Introduction.
The services described here were successfully
tested using the IBM Test Centre at Dallas TX, but work only with SOAP
services, not REST services, and only with ZOS, not Micro Focus. They also require that the mainframe LPAR
accept web requests from the URL specified, which is unlikely in a
high-security mainframe environment.
A major upgrade of Jazz Web Services
is planned to support INVOKE more completely.
You should consult Jazz Software to learn about this if you are planning
to develop something similar to the examples shown here.
Contents
A
Classical CICS Program to Invoke SOATest1
Exchanging
Data with SOA Objects
Dealing
with WSDL Conversion Errors
In a previous chapter, Providing Web Services, we learned about writing a program that can be invoked externally as a web service, and we tested it with a Windows program, SOAPUI. In this chapter we learn how to write requester programs, programs that invoke an existing web service much as SOAPUI did for our GetTimA and GetTimB progarms in Providing Web Services. Our first requester program will invoke the test service SOATest1 provided at http://www.jazzsoftware.co.nz/SOATesting/Service1.svc that we reproduced with our zOS services GetTimA and GetTimB.
SOATest1 is a very basic web service, essentially a “Hello World” kind of program. It is open to anybody, from anywhere in the world, it requires no authentication, and looks up no database: the only data that it uses is the name it is given in its input message, and the time from the clock on its server. When we click the link Test Data and Web Services on the JazzSoftware web site we see
Enter your name and click [Respond:]. The web page responds like this: -
To do this it has invoked a web service that simply returns the current time. Like a traditional “Hello World” program this has almost no real function, it doesn’t look up a database, nor require any authentication, it simply responds. I like to have slightly more logic than returning “Hello World” so it has been programmed to return the time so that each response will be slightly different.
Requester programs may themselves be web service programs, or they may be classical CICS programs displaying and responding to a 3270 screen. We’ll start with a classical CICS program.
A
Classical CICS Program to Invoke SOATest1
Now, let’s see how we can write a CICS/3270
program with Jazz that does the same as our web
page. The point of this is to prove that we’ve set up everything
correctly and so we can invoke a web service and get its response. First we start by writing
a simple CICS program, pretty much like the enquiry programs that we wrote
earlier but even simpler because we’re not going to look up a file. We start by creating a new basic CICS program
like this: -
Click [Finish]. Jazz has created this program: -
*# Last Updated by robertb at 26/11/2013 2:56:56 p.m.
PROGRAM
WST1 CICS INSCREEN(WST1S) TRANSID(TRW1) COMMAREA(WST1C) ;
* This very basic form has no logic, it is up to you to create the
screen and program that you want.
* An empty screen will have been generated
* A commarea with field "Function" will have been
generated
We add a couple of fields
into our program: -
DEFINE
Wrk DATA(
Name CHAR (20),
Result
CHAR (70));
Then we click the
[Screen] button and drag the two Wrk fields on to it so that the two fields
that we want are on the screen.
Result is going to be an output-only
field, so right-click the field on the screen to expose the field’s properties:
-
Uncheck Input and click
[Close]
Click [Process] to save
the screen and create it on our zOS test system.
Now we temporarily “complete” our CICS program by adding code to process the screen input and post a result. Add lines
Accept name;
wrk.result = 'Result for ' && name
&& ' goes here' trim;
Send Inscreen;
Click
[Check]. Jazz checks the code,
qualifying keywords etc: -
*# Last Updated by JazzUser at 15/09/2019
10:50:19 AM
PROGRAM WST1 CICS INSCREEN(WST1S) TRANSID(TRW1) COMMAREA(WST1C) ;
DEFINE Wrk DATA(
Name CHAR(20),
Result CHAR(70));
ACCEPT(WST1S.Name);
#562 I WST1S.Error used as message field
Wrk.Result = 'Result for ' &&
WST1S.Name &&
' goes here';
SEND Inscreen;
If you’re like me you’ll want to test your temporary program before developing it further to make it invoke the web service. To do this,
1. Click [Process] to create the program in the zOS system.
2. Enter CEDA commands like these into your CICS test system: -
DEF PROGRAM(WST1) GROUP(MANAJAZZ)
DEF MAPSET(WST1S) GROUP(MANAJAZZ)
DEF TRANS(TRW1) PROGRAM(WST1) GROUP(MANAJAZZ)
3. Enter transaction TRW1 to run the program
Web Service Discovery
Now it starts getting interesting as we replace the temporary assignment statement
wrk.result
= 'Result for '
&& WST1S.Name
&& ' goes
here';
with something to actually get the result from a web service. At the heart of our Jazz program will be an INVOKE statement where we link to the web service, pass it the value of Name and get back the value of Result. We’ll replace the assignment statement with something like
INVOKE SOATest1(Name) REPLY(Result).
In order to be able to
use a statement like this Jazz needs to know where to find the service, what
parameters to pass to it, what parameters it will get back. With each parameter
Jazz will need to know what format to use.
We need a DEFINE statement that
describes the format of the parameters.
How do we do this for a web service, which could have been created by
somebody unknown on the other side of the world? Actually it may be easy: write
INVOKE
?;
give Jazz the URI of the
web service, and then follow the dialog and everything will be done for
you!
Click [Check], and then
follow the dialog to discover the service and get its description.
Click Web Service Discovery for a description of this
dialog.
Conclusion
Where did the complexity go? In Service Oriented Architectures and Web Services: Introduction the standards that we had to follow seemed overwhelming, but our first CICS program invoking a web service seems quite trivial. Admittedly the system programmer had quite a bit of set-up to do if this was the first CICS project using web services, and getting the very first CICS ó Web service program running can be a real challenge. Once that is mastered however, with the techniques that have been discussed in this chapter you can write Jazz programs that use web services, and that provide web services to develop SOA systems of any complexity. You can get data from remote services and use it in your mainframe programs, you can provide mainframe data through web services to remote web pages and Windows programs, and you can develop distributed systems in which part of the data and logic is managed in the CICS environment, and the display and other parts of the logic is managed on a web server or client computer. For example, you can now write any of the Jazz programs that you wrote before with displaying the data on web pages rather than 3270-type terminals.
Our Jazz SOA programs have become even simpler than the corresponding CICS/3270 programs, but this is a bit deceptive. This reduced complexity has not disappeared, it has merely been moved from Jazz to Java or ASP.NET, as the remote objects have incorporated the validation logic. And without the benefit of the data definitions that have provided much of the power of Jazz’s validation logic, we have actually made more work for ourselves. Even when we use the ACCEPT statement to check that data returning from a web service is correct, the interplay between web service and service request can be much more complex than the validation logic implicit in ACCEPT with a 3270 screen named with INSCREEN.
To remind you: when we were working with 3270-type displays we could write
PROGRAM …. INSCREEN(screen) …
DEFINE Record1 DATA(
Field …)
and then create a screen by dragging fields to it. Jazz ensured that the screen field was appropriate for the dragged field, and when we wrote
ACCEPT (field)
Jazz would ensure that the field was validated according to the rules implied by its definition.
It would be great if we could write a program using INSCREEN, ACCEPT, and SEND much as we did before, but instead of being restricted to 3270 screens we could be using web pages or Windows. Then we’d get the best of both: the flexibility and power of web services, with the programming efficiency of displays built with an awareness of the data structure and rules. That’s the plan, but Jazz hasn’t implemented this yet.
this means that Jazz has been unable to convert the WSDL for this operation into a valid Jazz definition. If you select it anyway then Jazz will insert invalid code.