webMethods EntireX supports API Modeling with the IDL Extractor for COBOL and NATURAL

6 min readJan 31, 2023

We all know that API enablement of COBOL and/or NATURAL programs is easy with EntireX. In this article you will learn how EntireX allows for API modeling, as part of the IDL Extractor, where group data items from the extracted source can be excluded in the extracted IDL (API). This allows you to set IDL directions (IN, OUT) correctly. By Bernhard Fricke, Senior Software Specialist, EntireX Development and, Gadi Benedek, Director, Product Management, Adabas & Natural, Software AG

Introduction

Just in case you didn’t know — webMethods EntireX provides a cost-effective and efficient path for IT modernization and API enablement — whether you need to integrate Mainframe assets into process applications or elevate them to the digital economy through services.

EntireX gives new life to your core COBOL or NATURAL applications and helps leverage your investment in custom applications running on Mainframes by creating new services for use in modern applications with minimal effort and ZERO Mainframe footprint.

You can leverage programming logic and transactions from a wide variety of host environments to create new Application Programming Interfaces (APIs) for consumption by Java®, .NET® or any client applications as well as participate in the rapidly growing digital economy via REST.

In this article I want to focus on one common problem, and how it has been addressed with the latest EntireX 10.9 release. In this scenario the COBOL or NATURAL programs have a group data item structure defined which contains both input and output parameters. Why is this a problem? Let’s take a closer look.

The Problem

Hands-on example

Let’s look at such an example. In Fig. 1 you can see a code snippet for a COBOL group PAYMENT-DATA which contains input as well as output parameters:

ORDER-NUMBER and PAYMENT-TYPE are inputs.

PAYMENT-VALIDITY is an output parameter.

Since IDL directions can be set on IDL level 1 only, If PAYMENT-DATA is in the IDL, you need to map it to direction INOUT.

It is not possible to set it to direction IN because the direction of PAYMENT-VALIDITY would be wrong. The same applies if you set PAYMENT-DATA to direction OUT — ORDER-NUMBER and PAYMENT-TYPE would then be wrong. So, I guess you wonder what’s the problem if we set this to INOUT?

Mapping the group to INOUT means that ALL the group members will be sent, as part of the payload, for ALL transactions. Each call to PAYMENT-DATA will include the parameter PAYMENT-VALIDITY, even if it’s not needed as it will only show a value, as output, AFTER the transaction is executed. When the INOUT transaction returns after execution, with the output of PAYMENT-VALIDITY, it will also send the inputs ORDER-NUMBER and PAYMENT-TYPE along, even though they are no longer relevant for the output. Of course, this is a simplified example, but imagine how much waste can be sent over as payload when we have more complex programs with a lot of complex data groups.

The Solution

API Modeling with the IDL Extractor

The COBOL Mapping Editor and Natural Mapping Editor now support API modelling, where group data items from the extracted source can be excluded in the extracted IDL (API), but the subordinated data items remain.

This allows you to set IDL directions (IN, OUT) correctly, with the following advantages:

Reduced payload, which means less traffic at runtime.
The extracted API is simplified. For REST inbound scenarios, this means you can model the REST API more easily to simple HTTP GET methods without any input payload.
With the GET method, REST clients transfer level-1 input parameters as simple URL parameters — there is no request body.

In other words, EntireX v10.9 now offers an option to Ungroup the structure and flatten it to allow the subordinated data items to be IDL level 1 and get their correct IN/OUT setting.

In our example:

Remove the group data item PAYMENT-DATA with function Ungroup from the IDL Parameters context menu.
Map ORDER-NUMBER and PAYMENT-TYPE to direction IN.
Map PAYMENT-VALIDITY to direction OUT.

***Fig. 2:*** *Ungroup (Flatten) an IDL Group*

The result is this simplified IDL structure, where the inputs and outputs are correctly defined:

***Fig. 3:*** *The IDL with the new group structure*

Of course, this, in turn, will result in a simplified URL for the REST API, as there are only 2 inputs defined and only one output that will be sent as the payload.

EntireX documentation

For detailed information on COBOL, NATURAL, REST and other EntireX integration scenarios including extraction, generation of endpoints and CICS® IPIC Connections, please refer to Common Integration Scenarios in EntireX documentation.

Summary

As demonstrated, webMethods EntireX 10.9 offers a simple and elegant way of API modeling, which allows you to set IDL directions (IN, OUT) correctly. These simplified URLs can now be deployed into wM Integration Server to be integrated and consumed by any REST clients.

This isn’t just a minor cosmetic change, to have less parameters defined in the API signature, it has a real impact as it reduces the transferred payload, which means less traffic at runtime.

For REST inbound scenarios, where we are calling COBOL or NATURAL programs running on the Mainframe and expose them as APIs, this means you can model the REST API more easily to simple HTTP GET methods without any input payload and no request body.

Glossary of terms

Mainframe — are large computer systems produced by IBM

APIs — An application programming interface (API) is a way for two or more computer programs to communicate with each other

Java — a high-level, class-based, object-oriented programming language

.NET — a free and open-source, managed computer software framework

REST — Representational state transfer (REST) is a software architectural style that describes a uniform interface between physically separate components

URL — A Uniform Resource Locator (URL), colloquially termed a web address

IDL — Interface description language, any computer language used to describe a software component’s interface

IBM CICS® — Customer Information Control System is a family of mixed-language application servers that provide online transaction management and connectivity for applications on IBM mainframe systems

CICS® IPIC Connections — IP interconnectivity (IPIC) connections enable CICS® systems to communicate and share resources with each other

“webMethods EntireX will API enable your COBOL — using CICS IPIC, with zero backend footprint!”, TECHniques, October 2022 (Issue 4).
“Mainframe Integration made easy “, TECHniques, April 2016 (Issue 2).
“How to call webMethods Integration Server from COBOL — mainframe outbound”, TECHniques, October 2016 (Issue 4).
“How to call COBOL from webMethods Integration Server”, TECHniques, April 2017 (Issue 2).
“How to shape a call to COBOL from webMethods Integration Server — the modern way”, TECHniques, January 2018 (Issue 1).
“How to call COBOL on IBM i (AS/400) from Integration Server”, TECHniques, July 2018 (Issue 3).
“Publish your mainframe assets as REST Resources”, TECHniques, October 2018 (Issue 4).
“EntireX for CICS® Socket Listener — Integration with minimal mainframe footprint”, TECHniques, April 2019 (Issue 2).
“API enable your COBOL — with zero backend footprint”, *TECHniques, July 2019 (Issue 3).
“How to call a REST API from COBOL”, TECHniques, January 2020 (Issue 1).
“How to deal with COBOL REDEFINES?”, TECHniques, July 2020 (Issue 3).

This article is part of the TECHniques newsletter blog — technical tips and tricks for the Software AG community. Subscribe to receive our quarterly updates or read the latest issue.

Originally published at https://tech.forums.softwareag.com on January 31, 2023.