webMethods EntireX will API enable your COBOL using CICS IPIC

API enablement of COBOL programs is easy with EntireX. Learn how EntireX helps you salvage those COBOL treasures with just a few clicks and without having to install any EntireX components on the mainframe. Read on to see how the new EntireX 10.9 support for CICS IPIC connections is added to all other supported ZERO footprint scenarios available with EntireX.

By Bernhard Fricke, Senior Software Specialist, EntireX Development and Gadi Benedek, Director, Product Management, Adabas & Natural, Software AG

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 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.

You have been using CICS® to run business-critical and mission-critical COBOL applications for years, on a backend system like IBM® z/OS®. At the same time the rest of the world is talking about digital economies, API enablement and API management, while REST interfaces are the architectural choice of today.

Nowadays, new markets need to be addressed, and you are working on new applications using new technologies. These new applications need to be able to utilize your core COBOL CICS applications.

With EntireX you can easily merge the world of COBOL and the REST-driven API economy and CLOSE the integration gap between the ‘old’ and the ‘new’ worlds.

However, how can you connect these incompatible technologies?

How can you keep operation on mainframe to a minimum to minimize costs?

How can you avoid additional organizational costs? How can you save time for installation and configuration on the backend system?

The answer is ZERO backend footprint integration. Read how EntireX helps you to exploit your COBOL resources, without any additional installation on your backend systems, by making it easy to integrate these technologies.


Hands-on example

On the CICS® backend, Channel and Container programs play an important role for you, now and in the future, because they break the 32K data length restriction of traditional CICS COMMAREA programs. Let’s look more deeply at such an example.

Imagine an existing COBOL server (Fig.1) to an employee application with a LIST of employees and DETAILS of employee functions. The COBOL server is implemented with CICS channel containers. The DETAIL function is simple: it provides a single output container with the employee information. The LIST is more of a challenge: each employee item is provided separately with a CICS PUT CONTAINER command – so the LIST is formed by an array of containers.

With EntireX, you develop an API enablement scenario in three phases:

1. Extract the interface of the COBOL server

Fig. 1: API extraction of a COBOL Channel Container Server - eclipse EntireX perspective

In the Software AG Designer, switch to the EntireX perspective, select the COBOL server, invoke the IDL Extractor for COBOL and select the interface type of your COBOL server, in our example: CICS with Channel Container calling convention.

In the COBOL Mapping Editor, first select the COBOL layout of all input and output containers. Then map the EMPLOYEE-ITEM container – the list of employees – to an Array (Fig.1). This allows access to the list of containers as a JSON array in a REST client, or IDL array in arbitrary RPC clients.

For further mapping possibilities, refer to “How to call COBOL from webMethods Integration Server,” TECHniques, April 2017 (Issue 2). For advanced extractions resulting in user-defined mapping, see “How to shape a call to COBOL from webMethods Integration Server – the modern way,” TECHniques, January 2018 (Issue 1).

2. Generate an Integration Server service, REST resources and the API descriptor

Generating the IS service, REST resources and REST API descriptor is straightforward. In the context menu of a Software AG IDL file, choose Integration Server > Generate webMethods IS Connection; select the radio button “Create a new EntireX Adapter connection” and in the dropdown box choose “CICS IPIC Connection”; for API enablement check “Create or Update REST resource.”. Select the IS package and provide the host name of your CICS®. Press Finish (Fig. 2). To get a swagger file (RESTful API description) and for testing with swagger UI (eclipse view), create a REST API Descriptor. (Fig. 3). That’s it.

Fig. 2: Generate IS Service with Integration Server Wrapper – eclipse EntireX perspective

Fig. 3: Generate REST API Descriptor – eclipse Service Development perspective

3. Test REST client or Integration Server service to COBOL server.

To test the generated adapter service, use the service development perspective, as you do for every other IS service test. On the context menu of the generated IS service, select Run As > Run Service… (Fig. 4). For API enablement, use the REST API Descriptor created in step 2 as the input to the eclipse view Swagger UI to call the COBOL server (Fig. 4).

Fig. 4: Test with Run Service and Swagger UI – eclipse Service Development perspective

EntireX documentation

For detailed information on COBOL, REST and other zero-footprint scenarios including extraction, generation of endpoints and CICS® IPIC Connections, please refer to Common Integration Scenarios in EntireX documentation. EntireX zero backend footprint is also available for AS/400, z/VSE and z/OS – including IMS.

Fig. 5: EntireX documentation: Common Integration Scenarios


As demonstrated, it is quite easy to develop a scenario where webMethods Integration Server calls COBOL on the Mainframe. You do not need any COBOL know-how. You can rely on EntireX to do all the work for you from the design phase through runtime. COBOL-specific data types are mapped automatically to suitable Integration Server data types.

EntireX for CICS® IPIC allows you to call both CICS COMMAREA and CICS Channels and Containers programs from a webMethods Integration Server or from any REST clients directly, using ZERO mainframe footprint. Users of the EntireX RPC Server for CICS can move workload from CICS to other environments like Linux. This, together with its zero mainframe administration capabilities, helps reduce your mainframe costs.

Once EntireX is installed (off-host), using CICS IPIC connections allows you to call COBOL with zero footprint on the backend. This means no EntireX component whatsoever is installed on the system where the COBOL programs are executed. Once configured, zero footprint also means no further maintenance. On top of that, as most of the processing is done off-host, zero footprint with EntireX helps with keeping your backend costs to a minimum.

Glossary of terms

CICS® – IBM’s transaction container

COMMAREA – classic parameter area used by CICS® programs, data length limited to 32K bytes

CICS® Channels and Containers – modern way for CICS® programs to access parameters without data length limitation

IS – webMethods Integration Server

On-host – backend system like z/OS

Off-host processing – workload on a non-backend system like Windows or Linux

Related articles

  1. Mainframe Integration made easy”, TECHniques, April 2016 (Issue 2).
  2. How to call webMethods Integration Server from COBOL – mainframe outbound”, TECHniques, October 2016 (Issue 4).
  3. How to call COBOL from webMethods Integration Server”, TECHniques, April 2017 (Issue 2).
  4. How to shape a call to COBOL from webMethods Integration Server – the modern way ”, TECHniques, January 2018 (Issue 1).
  5. How to call COBOL on IBM i (AS/400) from Integration Server “, TECHniques, July 2018 (Issue 3).
  6. Publish your mainframe assets as REST Resources ”, TECHniques, October 2018 (Issue 4).
  7. EntireX for CICS® Socket Listener - Integration with minimal mainframe footprint ”, TECHniques, April 2019 (Issue 2).
  8. API enable your COBOL - with zero backend footprint ”, TECHniques, July 2019 (Issue 3).
  9. How to call a REST API from COBOL ”, TECHniques, January 2020 (Issue 1).
  10. 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.

1 Like