Jazz Setup and REST Services

If you use ZOS directly and you want to create SOAP (WSDL) web services, then the Jazz Set up says

If you are going to be creating SOAP (WSDL) services examine, and edit if necessary, templates JZWSProv.jzl, and JZWSReq.jzl.

You probably won’t need to make any change, if you do, the changes will be minor.

However if you want to create REST (JSON) services it says

If you are going to be creating REST (JSON) services, examine, and edit if necessary, templates JZJSProv.jzl, and create template JZWSReq.jzl if you want to write INVOKE xxx statements invoking a REST Service.  

This should be quite easy for your system programmers, but obviously not as easy as it would be if these templates existed as they do for SOAP.

Some background

When the MANASYS Jazz project started we used ZOS directly (the IBM Dallas Test Centre).  At that time web services meant SOAP, the only CICS web service type supported by standard CICS in 2015, so we developed and tested templates JZWSProv, and JZWSReq.  The compile job includes extra steps, based on these templates, to convert COBOL to/from WSDL.

SOAP has fallen out of favour and now it seems that everybody uses REST (JSON).  This is certainly the emphasis within Jazz Software.  We have developed REST support within MANASYS Jazz, with the only difference between SOAP and REST being a single option in the creation dialog.  However by 2016 we’d stopped using the IBM Test Centre, and instead our test environment became Micro Focus Enterprise Developer (MFED), which simulates a ZOS enterprise environment directly on our development computers (standard Windows 10 laptops).   The COBOL is identical, whether MFED or ZOS, but the way in which the binding objects converting between COBOL and WSDL or JSON are created is different: -

·         ZOS:   JCL steps (JZWSPROV, JZWSReq) are added to the job following the COBOL compile step to create the binding object (WSBIND, and the relevant message descriptions (WSDL or JSON).

·         MFED:  Following the COBOL compile a dialog is followed to create a Service Interface (.svi), the binding object (.wsbind), and the message descriptions (.wsdl or .json).

Thus we haven’t had an opportunity to create and test the JSON equivalents of the WSDL templates.  A template JZJSProv.jzl has been written, but we’re not sure if it is correct. We haven’t written JZJSReq.JZL.

We’d like your help to create these templates for all users. When you’ve created and tested them for your requirements will you please share them with us?  We’ll convert them into general templates and issue them to all users.

Client-Side Interfaces

A recent development in MANASYS Jazz is that MANASYS will generate client-side interfaces in C# to make working with your CICS Web Services.  This is only available for REST services, and will not be developed for SOAP services.  It is illustrated in this video.

Clicking the [Client] button will generate the C# interface, but to do this it needs access not only to your program (named “JSPG2” in my example), but also to the JSON descriptions of the request and response messages.  For program JSPG2, the input (request) message will be called “IJSPG2.json”, and the output (response) “OJSPG2.json”.  For [Client] to work these need to be copied back to your Windows project folder: -

Thus in my case you will want to copy the two .JSON files produced to C:\tutorials\TstSQL.

You should find the Manual FTP option of Process useful for this: with MANASYS configured for ZOS right-click [Process] to display the Process Options form. Note that at the bottom of this is a section “Manual FTP”: -

In the line Local, enter the location that you want to copy the JSON to.  The example above shows what I would enter to save the Request description for program JSPG2.   Request messages are named by adding suffix “I” (=Input) to the program name for the client, but prefixing “I” to the program name for the CICS Web service.  Click [Download].

When you’ve copied the Request message, repeat this for the Response using suffix/prefix “O” (=Output).

@hfs is the symbolic parameter for your ZOS Hierarchical File System.  A more modern name for this is zFS.