Jazz and the Maintenance of Existing Systems

Introduction - Jazz and Maintenance. 1

A scenario. 2

The VA Benefit Entitlement System.. 2

Creating Jazz Record Formats. 3

Developing our new Benefit Entitlement System.. 5

Ongoing Development 5

Introduction - Jazz and Maintenance

MANASYS-Jazz is a modern programming system for z/OS batch, Classical (3270-type) CICS, and Web Service development.  Jazz programs are concise – typically 1/20 or less the length of their COBOL equivalents – and Jazz ensures that record formats, generated screens and web services are all consistent and correctly integrated. For example, Jazz will discover external web services from their WSDL and ensure that the format of the messages that are sent to and from web services is the same format used by the service.  This translates directly into productivity gains. Click here to learn more about MANASYS-Jazz.

How does a new programming system, with a new language and new tools, help with a maintenance problem where the issue is not how to write a new system, it is to make a small change to a system developed with earlier technology that already exists? 

The answer: because Jazz is highly compatible with legacy technologies you can use it for the new functions, making only minimal changes (if any) to the unchanged parts of the existing system but gaining the productivity benefits of Jazz within the new function.  Jazz can import your existing COBOL record layouts, and web services message formats.  You can use Jazz to replace one or two programs within a larger system – perhaps a new report, a new screen dialog. You don’t have to undertake a “big bang” redevelopment of the whole system that would put your business at risk, instead you can progressively replace your system section by section. Each replaced program will be hugely simplified compared to the COBOL program that it replaces.  As you progressively do more and more of your work in Jazz you’ll realize greater and greater benefits.

Particularly relevant:  Jazz makes it easy to develop mainframe web service provider programs, and for your mainframe programs to request web services from external providers, whatever their host system.  This means that you can progressively evolve your classical CICS systems into modern systems where parts of the application run on the mainframe, parts run on UNIX systems, and parts run in client apps running in Windows, Android, IOS, and so on, with the logic drawing on the services of many suppliers.  Jazz is the easiest way to smoothly transition from your present world to the new world of distributed service oriented architectures, without risky “system conversions”.

Let’s see how this would be applied to a realistic, if imaginary, problem. 

A scenario

You are the CIO of Veterans Affairs. You manage a multi-million budget to provide services across the country to thousands of users, both your own employees and agents, and directly to your clients through the Internet.  Your IT environment includes a range of technologies: UNIX and Windows™ systems, as well as legacy zOS mainframes that still run your core systems developed many years ago in COBOL.  You are continually upgrading your systems to deal with the latest government updates and market requirements, but this is proving increasingly difficult and costly, especially as mainframe/COBOL skills become harder to find, even offshore. 

Perhaps you should develop a new system from scratch using Java or .NET. After all, it’s easier to find people with the skills to do this and with web pages and with Windows you can provide a much more productive user interface. But you aren’t sure that a cluster of cheap servers could service the batch and on line loads of your mainframe, and your career will be over unless you avoid the changeover disasters of other large organizations who have tried this.  For the time being at least you seem to be stuck with COBOL.  Certainly COBOL has developed a long way since the days of Grace Hopper, but it’s still COBOL. You can’t solve the problem by smoothing over the inadequacies of a 50-year-old language, or managing the complexity of web services with yet more integration software.  If you continue to enhance your systems in their legacy technology you perpetuate the problem. Yet if you redevelop them into new environments, you replace an old mess of legacy z/OS-COBOL code with a new mess of even more complex UNIX or Windows code.  Neither approach solves the problem.

Both old and new systems are complex but almost all of this complexity is caused by the solution, not by the actual business problem.  You’d like a solution that takes aim directly at system complexity and moves you smoothly forward from the legacy applications to the new world of 21st century computing. Is MANASYS-Jazz the answer?  You decide to try it out on a pilot project, managing benefit entitlement.  This is currently very complex, often requiring operators to use long sequences of 3270 screens to update records. If this could be managed through a web interface then efficiency would be greatly improved, and if the programming costs of keeping up with the many government changes could be slashed that would be an additional bonus.

The VA Benefit Entitlement System

Here is a simplified data model of the parts of our system that we might need to change: -

All of these are VSAM files.  The Veteran Masterfile is a very large file containing a record for every Veteran.  Linked to this are records (BNE) describing the benefits to which the veteran is entitled.  The Benefit Entitlements subsystem which we are going to redevelop in this pilot project updates BNT and BNE records, and writes BNEH records logging every change to a BNE record.  Currently the subsystem is mainly a 3270-type on line system, although there are also batch components and we also need to consider the Client Enquiry system which is a web-based system allowing veterans to view their data in a web browser. The new system will use web pages instead of 3270 screens.

Creating Jazz Record Formats

We start by creating Jazz definitions for the VMF, SVCR, BNT, and BNE record layouts by copying the COBOL record definitions into Jazz, and upgrading the definition to include information that the COBOL definition lacks.  The first minute of this video shows how easy this is.


Here is the definition of the BNE record converted from the COBOL copy book. For this demo comments like [Must exist in VMF have been added to show data rules of the system.

*# Last Updated by IBMUSER at 10/08/2014 5:29:22 p.m.



        VMFID CHAR(10),  [Must exist in VMF

        BNEType CHAR(3), [Must exist in BNT

        END GROUP,

    Commenced GROUP,

        Year PIC '9999',

        Month PIC '99',

        Day PIC '99',

        End GROUP,

    Terminated GROUP,  [May be absent

        Year PIC '9999',

        Month PIC '99',

        Day PIC '99',

        End GROUP,

    BNEStatus CHAR(1),  [A:Automatic Approval, R:Review needed, D:Declined, T:Terminated

    Notes CHAR(30));    [Usually absent


With complete record descriptions our systems have fewer errors and greater consistency.  Our objective is to make our record descriptions so complete that our program logic is reduced to nothing except business essentials.  We make these changes: -

1.      We add TYPE(VSAM) and DSNAME('@Project.VSAM.BNE') to the definition.  Now COPY BNE; in a Jazz batch program brings in all the information necessary to create JCL to read and write this file.

2.      The relationships of VMFIT and BNEType are no longer comments, but are written into the definition.  When the definition is checked (Jazz Workbench, click [Check] Jazz gives error messages if the relationship is incorrect: referenced fields like VMF.VMFID must exist, and must be the primary key of the relevant record.  We add COPY VMF; to the COPY BNE definition: it doesn’t matter if this duplicates other COPY VMF statements. 
When programs using this record validate the data (usually with ACCEPT from an input screen or message) values entered into this fields will be checked to ensure that the values exist within the related file.

3.      Commenced and Terminated are dates, stored in a format that is standard for the VA applications. We can define this as a data type VADate, making the definition more precise and briefer, and giving us a single place to write things like validation logic. We’ll create a copy book, VATypes, to hold this definition, as we expect more VA data types to be required as the project continues.

4.      We add OPTIONAL for fields that may be absent. In VSAM records, unlike SQL tables, optional fields are actually always present, but “NULL” or “OPTIONAL” means that they don’t have to be entered on an input screen.

5.      The status field is defined with CODES. Not only does this define the values that can be entered but it also defines what they mean so that any time the field is displayed (on a screen or report) its value will be “Approved”, “Review Needed”, etc, not “A”, “R”).


Here is the revised BNE definition.  Note that it now includes COPY for other definitions that are needed to complete this one or related to it.  

*# Last Updated by IBMUSER at 12/08/2014 2:14:43 p.m.







        BNEType CHAR(3) EXISTS BNT.BNType,

        END GROUP,

    Commenced LIKE VATypes.VADate,

    Terminated LIKE VATypes.VADate NULL,

    BNEStatus CHAR(1) CODES(A:Approved, R:'Review Needed', D:Declined, T:Terminated),

    Notes CHAR(30) NULL)    [Usually absent (blank)



We will have made similar changes to the other records.  As we have worked through the records we may have put more type definitions into VATypes: for example we might have defined the status code as a type, allowing us to write

                BNEStatus LIKE VATypes.STATUS,


As we do this more and more of the complexity of our old COBOL system becomes simply part of the data definition.  In the conversion from COBOL Jazz ignores the old COBOL procedure logic because it can’t distinguish statements that are merely present because the solution requires them from those that express part of the business logic.  Few COBOL procedural statements actually express business logic: almost all merely express solution logic.  For example, you don’t need the COBOL logic that relates to functions like

·         handling a file (OPEN, CLOSE),

·         accessing screens (EXEC CICS SEND MAP/RECEIVE MAP),

·         data validation (IF BNEStatus OF BNE = 'A' 'R' 'D' 'T'),

·         displaying data (IF BNEStatus OF BNE = 'A' BNEStatus OF PrintLine = ‘Approved’ …


Jazz can infer all of these from the data definition, so you don’t need to write procedural logic for this kind of function. 


With the records defined to Jazz it is now easy to write batch programs. If you haven’t already done so, see the rest of this video.  But the real task is to develop the new Benefit Entitlement subsystem. 

Developing our new Benefit Entitlement System

We will want this to operate in a web page.  Using our design tool of choice (Eclipse? Visual Studio?) we start designing and developing the application.  Very quickly we reach a point where operations require mainframe data, such as

            Get VMF record

            Check Benefit Entitlement

            Add New Benefit

and so on.   Each of these will become a Web Service provided by our CICS system.


This 3m video shows you how to develop a basic web service provider program.   With data definitions prepared for our VA Benefits Entitlement System, creating a web service provider to get a record isn’t much more difficult.  In the generation dialog we would name the record type that we want and Jazz would generate the appropriate logic to get the record and send its data back as a web service.   By checking ‘update’ as well, the Jazz logic handles update responses for Add/Update/Delete, using CICS-style pseudo locking.  With Classical CICS, Jazz would have saved a copy of the record in COMMAREA and on update checked that the record hasn’t been changed by another user.  With web services you can’t do that, so Jazz logic creates a record digest (hash) when a record is read, and then permits an update only if the returned digest is identical to the recalculated digest when the record is re-read.  Jazz wizards will handle multi-record (e.g. parent/child) updates.


Jazz is not (yet) helping with the client development, so it remains your responsibility to create appropriate client logic that will display the received data, and provide client-side validation for any input.  Any data transmitted back to the mainframe will be validated against the record definition before being accepted: a standard Jazz principle built into the code it generates is that data from external sources (web services, screens) is not trusted.


As we proceed our new system is emerging.  It is vastly simpler than the old COBOL system that it replaces, as most of the previous complexity has disappeared into the data definitions and much of the solution complexity has been removed.  When we are ready we can move our new system from the test environment into our production environment, ensuring that the services are properly secure and only available to authenticated users.  This is the same process as we would have used with a COBOL development, the only difference is that the development cost has been a fraction of what it would have been. After appropriate acceptance testing the new system is rolled out, and the old system retired.  In the transition period we have avoided any need to duplicate data between old and new systems, because the data has remained in VSAM on the mainframe.  We don’t even care if users can attempt to update the same records at the same time in old and new system – all this will be handled as smoothly as it would have been if both users were using the same system.


With the new system implemented, all access to the mainframe data is now through web services.  We can now consider moving the data off the mainframe into (for example) the UNIX environment: we can copy one file at a time and replace (experimentally) the relevant web services.  Are we getting the results we want?  Or without CICS’ ability to handle large numbers of concurrent users are we running into performance problems?   Either this is a success and we can move to this new file management, or it’s a success because we’ve safely found out that it won’t work without spending a lot of money and without another IT disaster.

Ongoing Development

MANASYS Jazz is a rapidly developing product, and we intend to allow our users to heavily influence our priorities and direction.  Currently our plans are: -

Short term (next six months)

·         Develop more videos showing the full process described above

·         Support SQL (DB2, Oracle), if required by one or more users.  Code for this is well understood and mostly developed already, but won’t advance without user involvement.

Medium term

·         Facilities for client-side programming.  From the Jazz record descriptions, provide code fragments in Java, VB, C# etc to reduce effort and improve client-side/mainframe consistency of display and validation.