How to call Natural from webMethods Integration Server - along the fast path

.pearl-hilighted-word {background-color: #ffffff !important; color: #000000 !important;}

Issue 3, 2016 Download PDF

webMethods EntireX

By Jürgen Lind, Senior Product Manager, Software AG
Bernhard Fricke, Senior Software Specialist, EntireX Development, Software AG

Calling Natural server from webMethods Integration Server is easy and straightforward with webMethods EntireX. In this article, we explore how you can connect new and old applications with EntireX to achieve quick results, without specific Natural knowledge.

Connecting new and old

Adabas & Natural have run your business-critical and mission-critical applications for years. You may be running them on mainframes for traditional reliability, availability, performance and security; or you may have re-hosted them to UNIX® or Windows®. Either way, these systems will continue to play a significant role in supporting your core business. This is not surprising given the huge investments organizations have poured into these core business applications over the years.

Today, you must also address new markets by defining new products and services faster than ever. These products typically require a digital representation, internet-oriented interfaces, and B2B and B2C scenarios. Fortunately, agile development methodologies are available to help you quickly build business applications for the digital age. You likely invested in new technologies like webMethods Integration Server (IS) to accomplish these objectives.

webMethods IS enables you to connect new technologies to a variety of Adabas & Natural applications and to batch processes. This ability to connect new technologies with your existing Adabas & Natural applications is preferable to reinventing your existing apps at a high cost.

Figure 1: Documentation Snapshot Showing the Integration Server --> Natural Scenario

So how do you connect these incompatible technologies? Do you need developers familiar with both technologies? Do you have them available? Can you find them on the market? No matter what your answer, webMethods EntireX can definitely support you. If you start using EntireX to integrate these technologies it will be easier than you think. Those irreconcilable technologies, originating from different decades, will work together seamlessly.

Hands-on example

Let us look more deeply into a concrete example. Imagine an existing Natural server called EMPLOYEE. It implements the access logic for a LIST and DETAILS function to a database view EMPLOYEE. Its Parameter Data Area is shown in Figure 2.

1 OPERATION        (A1)    /* 'L' => List; 'D' = Details
1 ID               (A10)   /* Input
1 EMPLOYEE                 /* Output
  2 FIRSTNAME      (A20)   /* First name
  2 SURNAME        (A20)   /* Surname
  2 DATE-BIRTH     (D)     /* Date of birth
  2 DETAILS        (A100)
    3 ANNUAL-SALARY(P9)    /* Annual salary
    3 VACATION     (N2)    /* Vacation days per year
    3 LANGUAGE     (A3)    /* Language
1 EMPLOYEES        (1:*)   /* Out
  2 IDENT          (A10)   /* Identification number
  2 FIRSTNAME      (A20)   /* First name
  2 SURNAME        (A20)   /* Surname
  2 DATE-BIRTH     (D)     /* Date of birth            

Figure 2: Parameter Data Area for Natural Server EMPLOYEE

You are developing a new application with webMethods IS. That application needs to access functionality available as a Natural Server. For you, the usage of the Natural server might be important for the following reasons:

  • It is heavily used by other existing Adabas & Natural applications
  • It contains complex consistency rules and duplication of those rules should be avoided
  • Re-using of the existing Natural server is reliable, saves costs and speeds up development time
  • It helps to finish your new project within the agreed time frame

As shown in Figure 3, you can develop the integration scenario with EntireX in the following three phases:

 1  First, you extract the interface of the Natural server subprogram.

 2  Second, you generate the webMethods IS service and connections.

 3  Finally, you test the call from webMethods IS service to the Natural server subprogram.

Figure 3: Documentation Snapshot Showing Development Steps for webMethods IS -> Natural Scenario

Extract the interface of the Natural server subprogram  1 

To extract from a Natural server subprogram, you do not need any specific Natural know-how. You simply follow these steps:

  • Switch to the EntireX perspective
  • Invoke the IDL extractor for Natural
  • Select the Natural server subprogram  4  (Figure 4) and press FINISH

Figure 4: Designer Snapshot on Selection of Natural Server Subprogram for Extraction

The default settings for the extraction ensure you get a useful result. The outcome is a Software AG Interface Definition Language (IDL) workbench file with the extension .idl as shown in Figure 5.

Figure 5: A Software AG IDL is the extraction result of a Natural server subprogram extraction.

The Software AG IDL file can be treated as an intermediate result required for further processing. It is the central starting point for all EntireX wrappers. EntireX usually generates communication source code for target endpoints from Software AG IDL. An IDL to programming language binding exists for every EntireX supported target endpoint. In EntireX terminology and documentation, the runtime objects built from this generated code are called interface objects. However, you do not need a deep dive into Software AG IDL. For those who are interested, refer to the EntireX documentation > Reference > IDL File.

In our scenario, the Natural server subprogram EMPLOYEE and the extracted interface EMPLOYEE match exactly 1:1, field by field, see Figures 2 and 5. By default, the interface name EMPLOYEE  4 (Fig. 5) and the IS Service name  5  (Fig. 9) are taken from the Natural server subprogram name, see  4 (Fig. 4).

Generate IS service and IS connection  

Generating the IS service and the IS connection is straightforward. Important settings are highlighted in the following designer snapshots Figures 6 to 8. If not already done, switch to the EntireX perspective. Use the context menu of the Software AG IDL file to start the EntireX webMethods Integration Server Wrapper as shown in Figure 6.

Figure 6: Designer Snapshot on IInvoking EntireX webMethods IS Wrapper

On the first page of the IS wrapper, shown in Figure 7, select the radio-button Create a new Integration Server connection; to connect to Natural select type EntireX RPC Connection too. Press NEXT for the second page.

Figure 7: Designer Snapshot on Selection of Connection Type for IS Connection

On the second page of the IS wrapper, shown in Figure 8, you specify the connection name and target package and folder.

Figure 8: Designer Snapshot on Specifying Connection Properties

Press Finish to get the IS service EMPLOYEE  5  (Figure 9) and IS Connection EmployeesConnection as the result:

Figure 9: Designer snapshot on generated EntireX adapter service Input/Output signature

You can use the generated EntireX adapter service like any other IS service—there is no difference. As the webMethods IS developer, you do not require any Natural specific knowledge on PDAs, LDAs, Subprograms, DDMs, CALLNATs, FUSER, FNAT, packed and unpacked formats, X-arrays, etc. EntireX takes care of mapping Natural specific data types automatically to suitable Integration Server data types. For example the Natural X- array EMPLOYEES (1:*)  (Fig. 2) is mapped to Integration Server document list EMPLOYEES  (Figures 9-10).

Test IS service to Natural server subprogram  3 

For testing, use the service development perspective, as you do for every other IS service test shown in Figure 10.

Figure 10: Designer Snapshots on Execution Results of Generated EntireX Adapter Service

For our IS service example EMPLOYEE, specify ‘L’ to invoke the LIST operation  6  (Figure 10). Similarly, you specify ‘D’ to call the DETAILS operation  7 (Figure 10). The interface requires exactly the same input as the original Natural server (Figure 2). Likewise, the output corresponds to the Natural server also.


As demonstrated in this article, it is quite easy to develop a scenario where webMethods IS calls Natural without requiring you to have any knowledge of Natural. You only need to select the correct Natural server as shown in Figure 4. You can rely on EntireX to do all the work for you from design phase through runtime. Natural-specific data types are mapped automatically to suitable Integration Server data types.

Did you know that with EntireX you can modernize your Natural server even further without any source modifications? Interested? Then look for our article “How to shape a call to Natural from webMethods Integration Server –the modern way” in this issue of TECHniques or read “Common Integration Scenarios” from webMethods EntireX documentation.

Glossary of terms

B2B – Business-to-Business
B2C – Business-to-Consumer
DDM – Data Description Module / DB view
FNAT – container for Natural system programs
FUSER – container for Natural user applications
X-Array – Array of variable length (Natural)
Packed - coding for numeric data on Mainframes
Unpacked – coding for numeric data on Mainframes
IDL – Interface Description Language
IS – webMethods Integration Server
LDA – Local Data Area (Natural)
PDA – Parameter Data Area (Natural)
Subprogram – Procedure (Natural)
CALLNAT – Execute a subprogram (Natural-Syntax)