How to shape a call to COBOL from webMethods Integration Server - the modern way
Tags: webmethods, entirex, cobol
Published: 2019-09-27 11:31:23

---
title: How to shape a call to COBOL from webMethods Integration Server - the modern way
published: true
tags: #webmethods, #entirex, #cobol
canonical_url: http://techcommunity.softwareag.com/techniques-blog/-/blogs/how-to-shape-a-call-to-cobol-from-webmethods-integration-server-the-modern-way
---

# webMethods EntireX

**Calling COBOL Server from webMethods Integration Server is easy with webMethods EntireX. Read how EntireX helps you to connect them, shaping the interface in line with your needs, even without specific COBOL knowledge.**

_Juergen Lind, Director, Product Management Adabas & Natural and  
Bernhard Fricke, Sr. Software Specialist, App Mod EntireX Development, Software AG_

| Issue 1, 2018 | [<font color="#000000"><img alt="" id="yui_patched_v3_11_0_1_1435667347988_855" src="http://techcommunity.softwareag.com/image/image_gallery?uuid=202eb7e1-9148-4c65-b29a-54c4302ab65e&amp;groupId=10157&amp;t=1326987658425" style="width: 22px; height: 22px; vertical-align: text-bottom;"> <span id="yui_patched_v3_11_0_1_1492771711676_1198">Download PDF</span> </font>](http://techcommunity.softwareag.com/ecosystem/download/techniques/2018-issue1/SAG_webMethods_EntireX_TECHniques_Jan18_WEB.pdf) |
|-|-|-|
This article is a follow up to “How to call COBOL from webMethods Integration Server” in TECHniques, April 2017 (Issue 2). The situation: You're developing a new application with webMethods Integration Server (IS). Your application needs to access complex functionality available in a COBOL server (Figure1). You have already successfully extracted and connected the COBOL server with webMethods IS following the fast path with quick results described in our article in the April 2017 TECHniques. There you ran through 3 steps:  1 extract,  2 generate,  3 test.

![](http://techcommunity.softwareag.com/documents/10157/9398481/entirex1.jpg/48fb30b3-5347-478f-8666-b3854b92d4de?t=1516181293458)

**Fig 1:**  COBOL server EMPLOYEE

In this article, you will learn how EntireX helps you shape the COBOL interface with a user-defined mapping to achieve an up-to-date interface from webMethods IS to your COBOL server. An important advantage of the process is that the COBOL program itself remains unchanged which is valuable especially if changing the back-end is not an option for you.

When shaping the COBOL interface with a user-defined mapping, you will reuse the results from the fast path extraction so you do not have to start from the beginning. The only step to be refined is the first  1 extract step. Steps  2 generate and  3 test are identical to the fast path extraction – there is no difference.

## Re-invoke COBOL Mapping Editor

First, make sure you are in the EntireX perspective of the Software AG designer. You invoke the COBOL Mapping Editor from the context menu of the Software AG IDL: COBOL \> Modify Interface (Figure 2; red markers), which needs refining from the previous fast path extraction.

![](http://techcommunity.softwareag.com/documents/10157/9398481/entirex2.jpg/53eb3eac-b696-4eb8-a976-6a9ee0243eaa?t=1516181297471)  
**Fig 2:** Reinvoke COBOL Mapping Editor

You may remember that a LIST and DETAILS function are provided in the COBOL server EMPLOYEE. The value in the OPERATION field defines which function is executed. In COBOL practice values are often available as COBOL Level-88 items, similar to an enumeration type (Figures 1+2; blue markers).

## Extract getDetailsOfEmployee function

In the COBOL Mapping Editor you shape the existing COBOL to IDL mapping from the previous fast-path extraction.

![](http://techcommunity.softwareag.com/documents/10157/9398481/entirex3.jpg/6619e0b2-a7a6-4500-84d8-176e0ab01fd7?t=1516181302745)  
**Fig 3:** Shape EMPLOYEE: Set constant and IDL interface name for DETAILS function.

First, you shape EMPLOYEE to _getDetailsOfEmployee_:

1. Mark the OPERATION field in the COBOL Interface pane and press the Set Constant button. In the pop-up window, select OPERATION-DETAILS (Figure 3; red markers). The OPERATION-DETAILS value originates from COBOL level-88 data item (Figure 1 and 2; blue markers). If there is no COBOL level-88 enumeration type in the COBOL program defined, you can enter the function code manually in the pop-up window.  
  
2. By default the IDL interface gets the same name as your COBOL server: EMPLOYEE. Use the _Rename_ button ![](http://techcommunity.softwareag.com/documents/10157/9398481/entirexicon.png/e30c5b29-019a-48a2-b5ee-326e68c5198a?t=1516182217896) from the toolbar of the COBOL Mapping Editor and change the IDL interface name to _getDetailsOfEmployee_ (Figure 3; blue markers). This name is used as the IS service name later.

![](http://techcommunity.softwareag.com/documents/10157/9398481/entirex4.jpg/14314499-cc00-442b-baf6-61f89d136e27?t=1516181308336)  
**Fig 4:** Shape getDetailsOfEmployee: Select REDEFINE and suppress IDL fields.

You continue shaping, making getDetailsOfEmployee easier to use:

1. Use the context menu of the redefinition of the DETAIL field in the COBOL Interface pane, FILLER REDEFINES DETAIL and select _Map to Out_ (Figure 4; blue markers). A redefinition is a secondary layout (field types) of the same memory area. The redefinition contains more specific information (ANNUAL-SALARY, VACATION, etc.) than character buffer DETAIL. This is the reason why it is more useful in your interface.  
  
2. Use the context menu of FILLER\_1 in the IDL interface pane and _Rename_ FILLER\_1 to DETAILS (Figure 4; green markers) for a readable IS service field name later.  
  
3. The DETAILS function in the COBOL server does not make use of the EMPLOYEES field. Therefore, you can leave it out of the interface: Use the context menu of the EMPLOYEES field in the COBOL interface pane and select _Suppress_ (Figure 4; red markers).

## Extract getListOfEmployees function

![](http://techcommunity.softwareag.com/documents/10157/9398481/entirex5.jpg/262618e1-b029-4399-9baa-90bc725c1863?t=1516181320813)  
**Fig 5:** Shape EMPLOYEE: Create second IDL interface mapped to same COBOL server.

The COBOL Mapping Editor allows you to define multiple IDL interfaces to the same COBOL server:

1. You create the additional IDL interface using the toolbar button  ![](http://techcommunity.softwareag.com/documents/10157/9398481/entirexcopy.png/e6a1d179-b8e6-45ad-8200-8b894c9bd6fd?t=1516182683700) _Copy current IDL interface_. (Figure 5; red markers). A new tab _getDetailsOfEmployee1_ is created. The previously extracted _getDetailsOfEmployee_ interface still exists in the first tab. Once you reactivate the first tab, you will see the interface of _getDetailsOfEmployee_ again.  
  
2. Use the _Rename button  ![](http://techcommunity.softwareag.com/documents/10157/9398481/entirexicon.png/e30c5b29-019a-48a2-b5ee-326e68c5198a?t=1516182217896) from the toolbar of the COBOL Mapping Editor and change the IDL interface name to _getListOfEmployees_ (Figure 5; blue markers). This name is used as the IS service name later.  
  
3. For the LIST function you need the OPERATION-LIST value in the OPERATION field: Mark the OPERATION field in the COBOL Interface pane and press the _Set Constant_ button. In the pop-up window, select OPERATION-LIST (similar to Figure 3; red markers).  
  
4. Use the context menu of the EMPLOYEES field in the COBOL Interface pane, EMPLOYEES OCCURS 1 TO 99 and select _Map to Out_ (similar to Figure 4; blue markers).  
  
5. Because the EMPLOYEE-DETAIL field is not used in the COBOL server LIST function you leave it out in the IDL interface: use the context menu of EMPLOYEE-DETAIL field in the COBOL interface pane and select Suppress (similar to Figure 4; red markers).

_Press Save._ The outcome is a shaped Software AG IDL (Figure 6) with a user-defined mapping. Generating the IS service and IS connection is straightforward: It is the same as described for the fast-path extraction step  2 generate.

## Shaped Software AG IDL, IS Service and IS Connection

Now, let’s look at the differences between the two approaches. How do the IS services look with a shaped extraction and user-defined mapping, compared to the quick result extraction?

![](http://techcommunity.softwareag.com/documents/10157/9398481/entirex6.jpg/70f72077-8438-4152-8d89-fab0791b44f0?t=1516181315696)  
**Fig 6:** Comparison: Shaped Extraction with User-defined Mapping Versus Quick Result Extraction

With a quick result extraction, the IS service fields match 1:1 to COBOL. For example: the LIST function contains unneeded IS fields EMPLOYEE, FIRSTNAME, SURNAME, etc. (Figure 6; red box). Further, the OPERATION field value ‘L’ needs to be specified (Figure 6; blue box).

With interface shaping, the interface is more self-explanatory with long readable IS service names. It is easier to use with the hidden OPERATION field (Figure 6; blue box) and suppressed IS fields EMPLOYEE, FIRSTNAME, SURNAME, etc. (Figure 6; red box).

Now take a look at the IS package. It appears with a modern interface and you would not suspect a COBOL program behind it.

## Comparison chart

The following table highlights the differences when shaping an interface with a user-defined mapping as compared to a fast-path extraction.

| **Interface shaping with user-defined mapping** | **Fast-path extraction** |
| --- | --- |
| **General** | User-defined interface with dedicated mapping | Automatic, quick result extraction with COBOL- like interfaces on IS |
| **IS Service(s)** | Multiple small and handy IS services; each OPERATION code is mapped to a separate IS service | One big IS service |
| **IS Service name** | Readable long name | Short subprogram name; up to 8 characters |
| **IS fields** | Usage of Suppress and Set Constant reduces the message length. This keeps focus on relevant data items and keeps the client’s interface clean. It may also improve performance. | The IS fields and COBOL server parameters match 1:1. As COBOL layout descriptions are sometimes used for many different purposes, irrelevant data items appear and clutter up the IS interface. |
| **OPERATION parameter** | Suppressed: The OPERATION parameter does not exist in the IS service as an IS field | The OPERATION parameter exists in the IS service as an IS field and needs to be filled-in by the client endpoint |
| **OPERATION** **code** | The OPERATION code is provided internally by EntireX runtime in the OPERATION field | The OPERATION code needs to be specified in the IS service in the OPERATION field by the client endpoint |
| **REDEFINE** **parameters** | Either the parameter which is redefined or one of its redefinitions is available as an IS field. | Only the parameter which is redefined is available as an IS field. Redefinitions of the parameter are not available as IS fields. |

## Summary

In this article you have learned the principle of interface shaping. You can modernize the view to the COBOL server without changing the COBOL server itself. This allows you to build your IS application on top of a modern interface.

If quick results are required, use the fast path extraction as described in the related article “How to call COBOL from webMethods Integration Server," TECHniques, April 2017 (Issue 2). You can rely on EntireX to map COBOL-specific data types automatically to suitable IS data types.

To learn more, read [Common Integration Scenarios](http://documentation.softwareag.com/webmethods/wmsuites/wmsuite9-9/EntireX/9-9_EntireX/scenarios/overview.htm) from webMethods EntireX documentation.


## Glossary of terms

**OCCURS DEPENDING ON table** – COBOL array of variable length

**REDEFINE** - same memory area described by different data items

**CICS****<sup>®</sup>**– IBM<sup><strong>®</strong></sup>transaction container

**COMMAREA** – classic parameter area used by CICS<sup>® </sup>programs

**CICS** <sup><strong>®</strong></sup> **ECI** – External Call Interface

**IS** – webMethods Integration Server

**IDL** – Interface Description Language

**User-defined mapping** - advanced extractions to shape a call to COBOL

**CVM** - client-side server mapping file resulting from user-defined mapping.


## Related article

See “[How to call COBOL from webMethods Integration Server](http://techcommunity.softwareag.com/techniques-blog/-/blogs/webmethods-entir-2)” in TECHniques, April 2017 (Issue 2).