How to shape a call to Natural from webMethods Integration Server—the modern way
Authored 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.
DEFINE DATA
PARAMETER
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)
2 REDEFINE DETAILS
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 7 (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 6 (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).
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
Summary
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
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