JazzUGSOA2.htm showed you how to develop your first web service, providing the time from your computer. JazzUGSOA4.htm extended this to more useful services, providing and updating data held in files on your mainframe. This chapter is about testing your web service providers, and developing web service clients – programs operating from Windows, a Web Page, or a mobile app that invokes the web services that you have developed with Jazz.
First we show you how to use a general test utility, SOAPUI, that can be used to invoke any web service. This is a convenient tool to use when a web service is being developed, especially when you want to find out if your new service is actually getting the messages that you send it, and responding with something, or when you aren’t sure whether an error is in the web service or in the client program.
Next we show you how to develop web pages accessing your services, documenting the development processes of pages on the JazzSoftware web site. My tool of choice is Microsoft’s Visual Studio, and details will differ if you are using other software such as Eclipse, but you will get enough from the Visual Studio examples to see how to do similar tasks in any tool set. For this chapter, the scenario is: -
1. My laptop has a Windows environment. Programs installed here include SOAPUI and Visual Studio.
2. Visual Studio can create web pages, which may be installed in a web site like http://www.jazzsoftware.co.nz or run from Visual Studio on the laptop
3. Web pages and SOAPUI can send SOAP messages to URI’s. If there is a web service listening at this URI then there will be a response of some kind.
4. Web services GetTime, WSPG1, and WSPG2 have been developed, as described in the previous chapters JazzUGSOA2.htm and JazzUGSOA4.htm. The services are running, so that if they receive a message they will respond.
Finally we discuss low-level debugging: using CEDX to step through the CICS commands in your web service programs.
SOAPUI is a free test tool, SOAPUI, that you can download here. I created a SOAPUI project: -
Click [OK] and the web service is discovered, and a project created. Expand the project to locate the request node, which is at the lowest level.
Double click this, and the test form opens. Fill in the input data (left hand panel), in this case giving the length and value for Name.
Then click and the message is sent to the service, and the results displayed in the right-hand panel: -
Note that we
didn’t have to give any information about the format or names of the messages,
the URI was sufficient to find the WSDL, and this gave SOAPUI everything it needed. In the same way we can create SOAPUI projects
to test WSPG1 using URI http://188.8.131.52:9014/MNJZPROV/WSPG1?wsdl, and WSPG2
using URI http://184.108.40.206:9014/MNJZPROV/WSPG2?wsdl. We can give a domain name in place of the IP
and port: for example we can create a SOAPUI test of the test services on the
Jazz Software web site with http://jazzsoftware.co.nz/SOATest1.svc?wsdl.
Note that we didn’t have to give any information about the format or names of the messages, the URI was sufficient to find the WSDL, and this gave SOAPUI everything it needed. In the same way we can create SOAPUI projects to test WSPG1 using URI http://220.127.116.11:9014/MNJZPROV/WSPG1?wsdl, and WSPG2 using URI http://18.104.22.168:9014/MNJZPROV/WSPG2?wsdl. We can give a domain name in place of the IP and port: for example we can create a SOAPUI test of the test services on the Jazz Software web site with http://jazzsoftware.co.nz/SOATest1.svc?wsdl.
When you formed the SOAPUI project the WSDL was read and the message formats retrieved. Especially during initial development these formats may change. If the input message changes its format then the test won’t work any more, but will fail with a SOAP error. Here’s an example from program WSPG2 testing: -
Here CICSFault has value
<CICSFault xmlns="http://www.ibm.com/software/htp/cics/WSFault">DFHPI1007 02/28/2016 15:20:56 CICSTS51 00477 XML to data transformation failed because of incorrect input (UNDEFINED_ELEMENT jz_custf_Skip) for WEBSERVICE WSPG2.</CICSFault>
To fix this, create a new web service. Unless you first delete the now-failing SOAPUI project, you’ll need to give it a different name. Here I deleted SOAPUI project WSPG2, then created a new one with the same name and URI as before. The web service is now invoked and results returned normally: -
The form of the WSDL reflects the Jazz input and output definitions, but has undergone some transformations. The message formats for GetTime were defined with VARCHAR fields: -
In the transformation from Jazz to COBOL the Varchar fields have become COBOL groups with a length field and a data field
001290 01 IGetTime.
001300 03 Name.
001310 49 JZL-Name PIC S9999 COMP-5 SYNC.
001320 49 JZD-Name PIC X(20).
Where you have used a COBOL reserved word this is prefixed with “JZ-“. Thus the field name “ERROR” becomes “JZ-ERROR” in COBOL.
In translation from COBOL to WSDL the hyphens become underscores.
All these changes are reflected in the message formats, so that we see a result like
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:get="http://www.GETTIME.IGETTIME.Request.com" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
The time in
Advantages of testing with SOAPUI, or similar tools, are: -
· You can quickly test a service, without any client-side programming
· You can see exactly what SOAP messages are being sent, and what are being returned
· You can easily test situations prevented by your client programs. For example, in the client page to test WSPG2 client-side logic prevents non-numeric data being entered into numeric fields, ensures that the value of BillingCycle is within the range 1 – 12, and so on. There is no problem testing these situations with SOAPUI.
The disadvantages: -
· It is possible for a client program to return different results. See A Client for WSPG2 for an example.
· Each test has to be carefully set up. With a VARCHAR field you must set the correct length as well as the correct text. When testing a program like WSPG2 you have to carefully copy Viewstate values from the output message to the next input message to test updating.
Using Visual Studio, relate to Eclipse, Rational, etc.
What you can write in client-side logic.
What you shouldn’t write – related updates (not recoverable if there’s a failure between part 1 and part 2)
To be written. This is carried-forward from previous text.
* * * * *
Rather more aesthetic: a page on the Jazz Software web site invokes this service and displays the returned results: -
1. Find a record by primary key
2. Record now found
3. Get records by Name. There are more than three
4. [Get From] lets us move up and down the list of records
To be written