Application Modernization requires Web Services.

Create CICS Web Services Quickly and Easily

"Application Modernization" doesn't mean "replace the mainframe". It means making your enterprise data available in the right way on the right platforms. This requires web services.

Why Develop Web Services?

A web service is like a web page, but its purpose is to provide information to another program, not a human reader. To do this it uses a number of standards, providing information as either a SOAP message, using WSDL, or a REST message, using JSON.

Basic connection technology like zOS Connect (that creates REST messages) is useful, but it’s not enough on its own. You don't want to leave it up to the UI developers to interpret the data. "If status code S1 has value 23 then this record has been flagged for review, also if status code S5 has value 'X' then notify the Police". Do you want this logic to be duplicated in every app that reads this record? Better to have a web service that encapsulates this logic (and other rules), returning a status code indicating success or problem, and a message such as “Notify Police” when appropriate. Jazz definitions with CODES and CONDITIONS properties encapsulate data meaning in ways that are obvious and easy to maintain, minimizing future maintenance costs.

And what if you need several records? Having retrieved a customer record, you need to get their latest purchase, and for each purchase line you want to get the product name from the product record ... Performance will suffer if each bit of information requires another request/response. A web service can assemble all the data you need in a single request/response. Again, the power of Jazz with EXISTS, KEY, and DKEY properties and simple GET and PROCESS statements, makes data relationships obvious and programming errors more difficult.

For anything more complicated than accessing a single record you'll need web service logic written in one of the languages supported by the server (COBOL, PL/I, Java, etc). But writing such web service programs is not easy. There is a lot of detail that you must get exactly right, especially if the service might update the data. MANASYS Jazz effortlessly handles this detail, leaving you to concentrate on the business problem.

Generating a Web Service with MANASYS Jazz

You start with the New Web Service dialog: -

· Choose message type: WSDL or JSON

· Choose Table 1 – either a database record or a VSAM record

· Optional: check [  ] update for Enquiry/Update/Add/Delete logic.

· Select which fields you want (default, all fields)

· Optional: select related table

· Click [Finish]

In seconds Jazz creates a web service communicating with SOAP (WSDL) or REST (JSON) messages, handling one or several records, using complete records or selected fields, and providing inquiry only or full update.  We started with this definition of the Employee record, which in turn was converted from the SQL table definition and required only slight editing, such as defining the key fields and some validation rules.  From this Jazz created this Jazz program, which in turn created this COBOL. MANASYS generates logic to ensure that all input fields are automatically validated, with errors being handled and appropriate messages returned.

In a fraction of the time it would have taken working directly in COBOL or Java you will have created easily maintained web services, with no compromise in efficiency or clarity. Including full validation of input data based on the implied and explicit validity criteria defined into the data definitions.

Ready-to-consume web services, hosted directly out of the mainframe, written by the people who understand the data.

This 6 minute video show you how easy it is, with an earlier version of MANASYS. This video shows a web service being developed with Micro Focus with the current MANASYS build, which supports DB2 and REST services as well as VSAM and SOAP. Skip the first minute if you’re not interested in Micro Focus.

Whether you use zOS Connect to manage the messages or not, MANASYS Jazz should be in every CICS Web Service developer's toolkit. 

Updating and Conversations

Web Services that provide data for display are conceptually simple, but there are challenges if they are to update it. Firstly, the input must be validated. We never assumed that setting the numeric property in a BMS screen map was sufficient, instead we checked that the data was numeric when our COBOL program received it. Similarly, we’ll validate data when we receive it from a service. MANASYS Jazz generates all of this validation automatically with its ACCEPT statement, so it’s cheap insurance, worth doing even when we wrote the client program ourselves and we know that some or all of this logic duplicates client-side logic.

Web service conversations present a further challenge. We were used to the classical CICS pseudo-conversation, in which one transaction read data, and a following transaction updated it. To avoid holding a record lock for a long period we used this logic: -

Transaction 1: Read data (don’t lock), save a copy in COMMAREA, and send the update screen.

Transaction 2: Read data with lock, compare it with saved copy
If different, message and abort (releasing lock)
Else do update and release lock

In Jazz, transaction 1 would use
GET record SAVECOPY(COMMAREA.SaveRecord);
and Transaction 2 would use
GET record CHECKCOPY (COMMAREA.SaveRecord);

But web services are self-contained and atomic, so we cannot pass intermediate data from one request/response to the next step in the conversation by saving it in COMMAREA or an equivalent. Everything they need must be available from their input message. Yet the need for a similar locking mechanism is at least as great.

We felt that including an unchanged reference copy as well the changed data in Transaction 2’s input message might have problems. Perhaps the record contains some fields that should not be displayed to the user. Or it might be possible to make changes to the reference copy to allow an invalid update.

Instead, Jazz implements CICS pseudo-conversation logic in web services using a checksum instead of a record copy. A checksum is a cryptographically secure hash total which can be calculated with
EXEC CICS BIF DIGEST RECORD(EMPLOYEE) … RESULT(CheckSum-Employee OF OWSPG2) …

The least change in the record will result in a different checksum value, but you cannot decrypt the checksum to find out the original record. With SAVESUM replacing SAVECOPY and CHECKSUM replacing CHECKCOPY, our program uses

WHEN (Enquiry);

…

GET Employee KEY(…) SAVESUM OWSPG2.CheckSum-Employee;

…

WHEN (Update);

…

GET Employee KEY(EMPLOYEE.EMPNO) UPDATE CHECKSUM IWSPG2.CheckSum-Employee;

When the client requests an update, the record is re-read and the re-calculated checksum is compared with the value returned in the input record IWSPG2.

Extending Generator Logic

Everything so far has required no programming other than using the New Web Service dialog. We could also have generated a program that could handle enquiry or update with a parent/child record hierarchy, like customer and order records. For a parent/child update Jazz will calculate and return checksums for the parent record and each of the child records: for a child process (say order processing) you return the checksums of both the parent record and the selected child record (order).

The dialog only handles these basic situations however, and real-life situations may require more flexibility. For example, you may be modernizing a classical CICS system, and you’re replacing a multi-step 3270 conversation with a single Windows™ program. You could generate web services to return each record individually when you want it, but if you provided a single service that read the customer record and returned this, plus related current orders, plus account details (all outstanding invoices, balances, and payments made in the last month) the initial response would not be noticeably slower, and then the user’s Windows™ program could respond instantly to whatever was asked. The generator can’t create this web service, but you could write it in Jazz. Or you could generate an initial program that did part of the job – say get the customer record and orders – and then extend this to do what you want. The message formats and the Jazz program are both fully editable, so that you can easily add logic to read and update other related records (purchase lines and product?) Jazz logic can handle almost anything that you can do in COBOL. If even that is insufficient, you can add your own COBOL logic.

Multi-service Updates (2-phase Commit)

Another problem is more difficult to solve. A CICS transaction can update two files, for example transferring value from one account to another, but neither update actually happens until the transaction ends. All or nothing, both updates or neither happen, even when the two updates occur on different computers (provided that they are managed by cooperating CICS systems).

Unless one or both updates occur though a web service! With logic
INVOKE WebService1 (…) REPLY(…)
INVOKE Webservice2 (…) REPLY(…)
Webservice1 will have already updated data before Webservice2 is invoked. If Webservice2 fails, then the WebService1 update must be reversed. Or else WebService1 must be designed to support a 2-phase commit, first making a provisional (uncommitted update), and then invoked again with a “COMMIT” or “ROLLBACK” function when the controlling program is terminating.

Difficult to solve, but not impossible. Contact us if you need this facility, and we’ll work with you, adding features to MANASYS Jazz to support two-phase commit in your programs.

Further Information

For a general introduction to MANASYS Jazz, start with our web page. There a range of videos, including the two linked above, give an overview of the main capabilities of MANASYS Jazz.

Full information is available from the Help and Training Page As well as repeating the overview videos, instructional videos provide an on line course in using MANASYS Jazz, and links to the top levels of Help pages provide access to categories of information, including

Users’ Guide Tutorial web pages showing you how to use Jazz for a variety of programming tasks. Pages relating to web service providers are

Service-Oriented Architectures and Web Services introduces the concepts and terminology of Service Oriented Architectures.

Providing Web Services shows you how to write a basic web service provider.  

Real Web Services. Now we start to deal with real problems: accessing data from a VSAM record and updating it

Web Services and Multiple Records.  Here you learn how to write web services that handle record hierarchies (think Customer/Order) and other record collections.

Language Reference A series of pages defining and describing the Jazz programming language

Click Get Jazz on our web page to download an evaluation copy of the software. Contact us if you have any questions.