How to call Natural from webMethods Integration Server - the modern way


Issue 3, 2016 Download PDF

How to shape a call to Natural from webMethods Integration Server—the modern way

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) is easy with EntireX. Learn how EntireX user-defined mappings can help you to connect them with an interface that meets your needs, even without specific Natural knowledge. This article is a follow up to the TECHniques article “How to call Natural from webMethods Integration Server—along the fast path.

Modernize your Natural Server user interface

With user-defined mapping, EntireX allows you to extract your Natural Server as a modernized interface. Consequently, your webMethods Integration Server (IS) can call your Natural Server with an interface different from its original implementation. There are no source modifications in the Natural Server. The EntireX runtime takes care of the relevant transformations. 

With modern endpoints, like Web services or object-oriented programming languages, it is quite common to have multiple interfaces (methods) to a single runtime instance (object). Keeping all interfaces (e.g., list, get, update, delete) of an object type together is good practice. Astonishingly, programming experts of the ‘80s and early ‘90s—when procedural programming languages were most popular—had a very similar idea. They often used a function code or operation code field instead of defining multiple interfaces for a single module in the programming language itself. Together with redefined layouts or other techniques, multiple interfaces were thus created pragmatically. A practical example demonstrating this aspect is the Natural server EMPLOYEE. The OPERATION parameter values ‘L’ LIST and ‘D’ DETAILS represent distinct interfaces implemented into a single module as shown in Figure 1.

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 1: Natural Server EMPLOYEE Implementing Multiple Interfaces

EntireX allows you to extract all implemented interfaces of the Natural server separately. As a result, your generated EntireX adapter for the webMethods IS provides a getListOfEmployees and a getDetailsOfEmployee service rather than a big EMPLOYEE service. Each service interface contains required parameters. Obsolete parameters for a service are suppressed, improving its usage. Your newly generated EntireX adapter does not have 1:1 mapping to the field level anymore, as would be the case if you used a quick and fast extraction (see TECHniques article “How to call Natural from webMethods Integration Server– along the fast path”).

For this purpose, you define a so-called user-defined mapping. During runtime, EntireX considers those user-defined mappings and takes care of correctly mapping to the target Natural server. The basic steps shown in Figure 2 are the same as with any IS --> Natural scenario.

 1  Extract

 2  Generate

 3  Test

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

Extract the interface of the Natural Server subprogram  1 

To extract the Natural server with a user-defined mapping from Software AG Designer, invoke the IDL extractor for Natural, select the Natural server EMPLOYEE, check Redesign the interfaces  4  (Figure 3) and press Next. 

Figure 3: Designer Snapshot with Marked Checkbox Redesign the Interfaces 

Let’s now model the extracted interface to suit your needs by creating a function getListOfEmployees (Figures 4-6). First, mark the parameter OPERATION in the source view  5  (Figure 4) or the Natural parameter pane  6  (Figure 4). Second, Set Constant ‘L’ for the parameter OPERATION. In the Natural parameter pane  6 (Figure 4), constant [L] is shown in brackets after the Natural parameter. OPERATION is removed from the IDL interface (Figure 4). During runtime, EntireX passes ‘L’ as the value for the OPERATION parameter. This forces the EMPLOYEE LIST function to be executed.

Fig. 4: Designer Snapshot Set Constant to Natural Parameter in User-defined Mapping

Because the Natural group EMPLOYEE is unused in the LIST function, you suppress it. Subsequently, the IDL group EMPLOYEE is removed from the IDL interface  8 (Figure 5). The Natural parameter EMPLOYEE  9  (Figure 5) remains. Parameters that are suppressed in the IDL interface are displayed in italic font in the Natural parameters pane  9  (Figure 5). Note, parameters set to constant are displayed in italic font  (Figure 4) because Set Constant suppresses them in the IDL interface too  7  (Figure 4).

Figure 5: Designer Snapshot Suppress Natural Parameter in User-defined Mapping

With the toolbar button  you can specify a readable name getListOfEmployees for the IDL interface. The name is displayed on tab  10  (Figure 6). In addition, it is used as the IS service name later (Figures 15 and 16).

Figure 6: Designer Snapshot Rename IDL Interface in User-defined Mapping

Now that the getListOfEmployees function is done, Let’s do the same for the DETAILS operation and create a getDetailsOfEmployee function—an additional interface is needed for this. To create the additional interface, you will  use the toolbar button   11 (Figure 7) and open a new tab. IDL parameters are reset to defaults. The previously extracted getListOfEmployees interface still exists in the first tab  12  (Figure 7). Once you reactivate the first tab, you will see the interface of getListOfEmployees again. 

Fig. 7: Designer Snapshot Create IDL interface in User-defined Mapping

Again, here you specify a readable name getDetailsOfEmployee for the IDL interface using the toolbar button  (see Figure 6). The name is displayed on the tab  12 (Figure 8).  As before, this name is used once more as an IS service name (Figures15 and 17) later.

Figure 8: Designer Snapshot Rename IDL Interface in User-defined Mapping

To execute the EMPLOYEE DETAILS operation at runtime, Set Constant ‘D’ for Natural parameter OPERATION. The IDL parameter OPERATION is removed from the IDL interface and displayed in italic font in the ‘Natural Parameters’ pane (Figure 4) in order to indicate this suppression.

Figure 9: Designer Snapshot Set Constant to Natural Parameter in User-defined Mapping

In the DETAILS interface, you do not need the Natural X-array EMPLOYEES so you can Suppress it completely (Figure 10). By doing so, the IDL parameter EMPLOYEES is removed from the IDL interface and displayed in italic font in the “Natural Parameters” pane (Figure 5).

Figure 10: Designer Snapshot Suppress Natural Parameter in User-defined Mapping

By default, the Natural parameter DETAILS  14  (Figure 11) is mapped. In this case, the redefinition of DETAILS  15  (Figure 11) contains information of more value.  

Figure 11: Designer Snapshot with Redefined Natural Parameter DETAILS

You may prefer to use the redefinition of DETAILS  15 (Figure 11) instead of the DETAILS parameter  14  (Figure 11). To do this, you map the redefinition to the IDL interface. Simply select the REDEFINE DETAILS in the ”Natural Parameters” pane and press Map to Out (Figure 12). The IDL parameter DETAILS is turned into a group  16  (Figure 12) containing parameters that match the Natural redefinition  15 (Figure 11).

Figure 12: Designer Snapshot Redefinition of Natural Parameter DETAILS Mapped to IDL Interface

We’re almost done. Press the FINISH button to retrieve the extraction result in form of a Software AG IDL. At the same time, a server mapping file for Natural (workbench file with extension .cvm as shown in Figure 13) is created. The Software AG IDL describes the interfaces from the webMethods IS perspective (i.e., RPC client view), while the server mapping contains the mapping to the real Natural Server. Both of these files must be kept together and in sync, otherwise a call to the Natural server may fail.

Figure 13: Designer Snapshot on Extraction Result for Software AG IDL and Server Mapping File for Natural (Workbench File with Extension .cvm)

Let’s summarize what we have done. We defined two IDL interfaces. In the Software AG IDL, these resulted in two IDL programs: getListOfEmployees and getDetailsOfEmployee  17  (Figure 14). Both IDL programs are given readable names (Figures 6 and 8). Meaningful fields have been kept while superfluous fields have been suppressed (Figures  10 and 5). The getDetailsOfEmployee contains the redefined fields of parameter DETAILS  18  (Figure 14) mapped during extraction  15  (Figure 11).

Please note that the Natural server and the redesigned interfaces do not match anymore! The webMethods IS (RPC client) will send data for the redesigned interfaces while your Natural server still expects EMPLOYEE data. The EntireX runtime transforms the incoming data stream from the RPC client using the server-mapping file.

Figure 14: Designer Snapshot of Extraction Result for Software AG IDL

Generate IS service and IS connection  2 

Even if there is a user-defined mapping, you generate the IS connection and IS service as usual. Use the context menu of the Software AG IDL and invoke Integration Server > Generate webMethods IS Connection. Two IDL programs (Figure 14) results in two webMethods IS services being generated: getListOfEmployees and getDetailsOfEmployee. In addition, the EmployeesConnection is generated as shown in Figure15.

Figure 15: webMethods Administrator Snapshot of Generated EntireX Adapter Employee Services

Test IS service to Natural server subprogram  3 

To run the services  19  (Figures 16 and 17), we do not have to specify operation codes anymore. On output of the getDetailsOfEmployees service, the redefinition of the DETAILS group is directly available  20  (Figure 17).

Figure 16: Designer Snapshot Run of getListOfEmployees Service

Figure 17: Designer Snapshot Run of getDetailsOfEmployee Service

Comparison chart

Table one highlights the differences between shaping an interface with a user-defined mapping and fast extraction, where a quick result is required, as described in the article “How to call Natural from webMethods Integration Server–along the fast path.”

  Interface shaping with user-defined mapping Quick result extraction
IS Service(s) Multiple small IS services where 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 and improves performance The IS fields and Natural server subprogram parameters match 1:1
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
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
REDEFINE parameters Either the parameter which is redefined or one of its redefinitions is available as an IS field Only the parameter that is redefined is available as an IS field; Redefinitions of the parameter are not available as IS fields

Table 1: Comparison Chart


With a user-defined mapping, you can shape the interface to your Natural server. You can minimize the interface by suppressing Natural server fields or by providing constant values. Renaming interfaces allows you to specify a readable long name. Together—constants and renaming of interfaces—are most powerful when multiple interfaces are implemented in a single Natural server. Each function of the Natural server triggered by an operation code or function code can be modelled as a separate IS service. 

To learn more, read Common Integration Scenarios from webMethods EntireX documentation and our TECHniques article “How to call Natural from webMethods Integration Server—along the fast path.

Glossary of terms

User-defined mapping – advanced extractions to shape a call to Natural
CVM – client-side server mapping file resulting from user-defined mapping
IDL – Interface Description Language
REDEFINE – Natural statement allowing multiple definitions for same data locations
Packed - storage format for numeric data on Mainframes
Unpacked – storage format for numeric data on Mainframes 
X-arrays - array of variable length (Natural)
IS – webMethods Integration Server