How to deal with COBOL REDEFINES?

#webmethods #cobol #entirex #rest

webMethods EntireX

If you create integration scenarios with COBOL on the backend, you’ll have to deal with typical COBOL programming patterns and COBOL syntax. One of these is REDEFINES. See how EntireX can help you deal with them.

By Juergen Lind, Director Product Management Adabas & Natural and Bernhard Fricke, Sr. Software Specialist, EntireX Development, Software AG

A REST Scenario with COBOL REDEFINES

Let’s dive right into a real-world COBOL integration scenario.

Imagine a typical COBOL server application, running on a mainframe, which gives you the option to LIST, UPDATE, DELETE and ADD to an order catalog. Each function is different in nature, using various COBOL data items. For easier extension and maintenance, the COBOL programmer implemented each operation into a separate function module. For simplified usage, there is a central entry point for developers to call the functions–a so-called dispatcher. Depending on the operation code, the dispatcher calls the desired function module. In such dispatchers you often find a set of REDEFINES to describe both the input of the request as well as the output of the response.

See the following architecture of an integration scenario with REST API and COBOL on the backend:

Figure 1: Architecture scenario: Provide REST API from COBOL

In a situation like this, you will have to deal with the COBOL REDEFINES. You will extract these redefinitions of data items in order to shape a pleasing REST API.

Getting to know COBOL REDEFINES

But let’s step back and have a look at typical COBOL syntax. Let me quickly explain how to read COBOL syntax and source code layout. You may want to skip this section if you are already familiar with COBOL

COBOL Layouts

Any data item (field) listed in a lower level (higher number) is part of a data item (group) in a higher level (lower number). For example:

02 VEHICLES-DETAILS. 03 MODEL PIC X(20). 03 MANUFACTURER PIC X(20).

The data items MODEL and MANUFACTURER are subordinated to (belong to) the group VEHICLES-DETAILS.

COBOL REDEFINES

REDEFINES allow the same memory area to be described by different layouts. Example:

02 VEHICLES-DATA PIC X(4954).02 VEHICLES-DETAILS REDEFINES VEHICLES-DATA. 03 MODEL PIC X(20). 03 MANUFACTURER PIC X(20). . . . 02 VEHICLES-LIST REDEFINES VEHICLES-DATA. 03 VEHICLES-COUNT PIC 9(8) BINARY. 03 VEHICLES OCCURS 99. 03 IDENT PIC X(10). . . .

VEHICLES-DATA is the redefined data item, the base of the redefinition. VEHICLES-DETAILS and VEHICLES-LIST are the redefining data items. Together with their subordinated data items (level 03 in the above snippet), each redefining data item forms a redefine path–describing a completely different layout.

Because all redefine paths are making use of the same memory, this can be problematic. Assume data originating from VEHICLES-DETAILS is in the redefined memory. Using the VEHICLES-LIST redefinition to interpret this data does not lead to success. Even worse, its misinterpretation may lead to an abnormal result or an exception. In Mainframe jargon, the exception is called an ABEND (abnormal end).

How does this relate to extraction?

During extraction (design time) you design the input data items (request document) and the output data items (response document) of an API. If REDEFINEs are used to describe them, extracting means it is vitally important to select the correct REDEFINEs for input and the correct REDEFINEs for output.

It goes without saying that it is very important to provide the correct REDEFINE structure on input to a COBOL function, when an API is consumed. If there is a mismatch between the REDEFINE structure and the COBOL function called, the backend server application on the Mainframe runs into an ABEND. This is of course equally true vice-versa: a correct interpretation of the API response is only possible using the right stencil describing, and thus matching, the output.

If the extraction is correctly performed, the extracted API no longer contains a set of REDEFINE structures; instead it contains one correct structure. This simplification means users of the extracted API are shielded from exceptions (ABENDs) arising from the use of wrong input and output structures.

Deep dive into extracting COBOL REDEFINES

The COBOL mapping editor of the IDL Extractor for COBOL assists you in extracting COBOL REDEFINEs with decision icons. If you are not familiar with extracting COBOL using EntireX tooling, refer to EntireX documentation or the related articles “How to call COBOL from webMethods Integration Server”. TECHniques, April 2017 (Issue 2) and “Publish your mainframe assets as REST Resources”. TECHniques October 2018 (Issue 4).

Figure 2: IDL Extractor for COBOL - COBOL Interface Pane: Decision icons (marked orange) for attention

In the left margin of the COBOL Interface pane, orange-marked decision icons (Figure 2) are displayed where particular attention is needed. The icons in the picture visualize a COBOL REDEFINE. Hover over them with the mouse to get a tooltip. A mouse click presents a context menu with more detailed explanations and possible actions. As explained in the sections above, it is essential that you map the correct REDEFINE path for your mapping.

Figure 3: IDL Extractor for COBOL - COBOL Interface Pane: Horizontal bars (marked orange) for orientation

Those decision icons are displayed in sync with the COBOL data items in the COBOL Interface pane. If you do not see a COBOL data item, you do not see its decision icon. Therefore, its visibility depends on how many COBOL data items are in your COBOL Interface, whether they are collapsed or expanded, and the excerpt of the COBOL data items created by using the slider on the right-hand side of the COBOL Interface pane (marked blue, Figure 3).

Luckily there is an additional place in the COBOL Interface pane for orientation. Notice the horizontal bars (marked orange, Figure 3) on the right-hand side of the COBOL Interface pane. They are independent of the displayed COBOL data items. Press (marked green, Figure 3) and expand the COBOL data items in the COBOL Interface pane to see all locations (horizontal bars marked orange, Figure 3) where user attention and a decision is necessary. Hover over the horizontal bars with the mouse to get a tooltip. A mouse click on the horizontal bar positions the COBOL Interface and IDL Interface pane accordingly where decisions have to be made

Summary

In this article you’ve learned about what COBOL REDEFINES are and how you can nicely map them with EntireX. You have learned why it is important to pay particular attention to these COBOL REDEFINES when you create an integration scenario, and how the EntireX COBOL Mapping Editor assists you.

To learn more, read: “IDL Extractor for COBOL” from webMethods EntireX documentation by Jürgen Lind, Senior Product Manager, Software AG and Bernhard Fricke, Senior Software Specialist, EntireX Development, Software AG

Glossary of terms

API – Application Programming Interface

API Consumer - Instance consuming, i.e. calling a REST API

API Provider - Instance providing a REST API for consumption

COBOL REDEFINE - Reusage or overlay of same memory areas

COBOL Mapping Editor - First stage to design the interface for API providers during COBOL extraction

data item - field or variable; can be a parameter used for input and/or output

IDL – Interface Description Language

Redefined data item - base field or variable; overlaid by a redefining data item

Redefining data item - field or variable which overlays the redefined data item

REST – REpresentational State Transfer: A paradigm that allows to describe structure and behavior of the World Wide Web