How to shape a call to COBOL from webMethods Integration Server - the modern way

Knowledge base
, , , , , , , ,
1

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.

Authored by Juergen Lind, Director, Product Management Adabas & Natural and
Bernhard Fricke, Sr. Software Specialist, App Mod EntireX Development, Software AG

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.

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.


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.


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

762×462 79.8 KB

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


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

736×736 132 KB

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 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® – IBM® transaction container

COMMAREA – classic parameter area used by CICS® programs

CICS® 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” in TECHniques, April 2017 (Issue 2).