Calling Natural from Integration Server

Scenario: "I have a Natural server subprogram and want to call this from the Integration Server."

This scenario uses the EntireX Workbench tools IDL Extractor for Natural and Integration Server Wrapper of the Software AG Designer.

graphics/simple.png

This document covers the following topics:


Introduction

To call a Natural server subprogram from the Integration Server, take an existing Natural server graphics/blue_1.gif and generate the integration logic graphics/blue_2.gif to call it from IS platform graphics/blue_3.gif, as shown below.

graphics/solution.png

graphics/blue_1.gif Extract the interface of a Natural server. See Using the Software AG IDL Extractor for Natural.
graphics/blue_2.gif Generate Integration Server adapter service and adapter connections. See Using the Integration Server Wrapper.
graphics/blue_3.gif Execute call from Integration Server service to Natural server.

This scenario makes the following important assumptions:

For Task 1:

  • You have a working Natural subprogram, also known as a CALLNAT program.

  • You have access to the sources of this Natural subprogram. These must be stored either

    • locally, that is, on the same machine where NaturalONE is running

      graphics/intro-local.png

    • or remotely and accessed via the Natural RPC Server (1), and either EntireX Broker or Integration Server.

      graphics/intro-remote.png

      Instead of NaturalONE, you can also use the EntireX Workbench.

      graphics/intro-remote-exx.png

    (1) See your Natural documentation for setting up the Natural RPC Server.

For Tasks 2 and 3:

  • You have an Integration Server with EntireX Adapter installed.

  • You can call the Natural server subprogram at runtime using different methods:

    • For the EntireX RPC connection method you need

      graphics/intro-rpc.png

    • For the EntireX Direct RPC connection method you need the Natural RPC Server (1)

      graphics/intro-direct.png

    (1) See your Natural documentation for setting up the Natural RPC Server.

Task 1: Extract the Interface of a Natural Server

Introduction

Follow the instructions for extracting Natural under Using the Software AG IDL Extractor for Natural:

This process creates the following EntireX metafiles:

  • IDL file. A Software AG IDL file contains definitions of the interface between client and server. See Software AG IDL File in the IDL Editor documentation.

  • Server mapping file (optional). The mapping file is an EntireX Workbench file with extension .cvm that contains Natural-specific mapping information. See Server Mapping Files for Natural in the EntireX Workbench documentation.

Sample Natural Server used in the Examples

The following Natural server is used to illustrate the features of the IDL Extractor for Natural.

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 below:

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             
END-DEFINE

Two approaches for extracting the Natural server are described below:

  • Fast-track
    Learn how EntireX helps you to connect the Natural Server with quick results, even without specific Natural knowledge. See Extracting a Natural Server - Fast-track Method.

  • User-defined Mapping
    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. These two features 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. See Extracting a Natural Server - Modern Method with User-defined Mapping.

Extracting a Natural Server - Fast-track Method

Start of instruction setTo extract the Natural server

  1. Switch to the EntireX perspective.

  2. Invoke the IDL Extractor for Natural.

  3. Select the Natural server subprogram, in this example EMPLOYEE, and press Finish.

    graphics/extract_fast-1.png

    The default extraction settings ensure you get useful results. The outcome is a Software AG IDL file (interface definition language), a Workbench file with extension .idl:

    graphics/extract_fast-2.png

    In our scenario, the Natural server subprogram EMPLOYEE and the extracted interface EMPLOYEE match exactly 1:1, field by field. By default, the interface name EMPLOYEE is taken from the Natural server subprogram name.

Extracting a Natural Server - Modern Method with User-defined Mapping

EntireX allows you to extract all implemented interfaces of the Natural server separately. Instead of a large EMPLOYEE interface, separate interfaces getListOfEmployees and getDetailsOfEmployee are extracted. Each interface contains required parameters; obsolete parameters for an interface are suppressed, improving its usability.

Start of instruction setTo extract a Natural server with a user-defined mapping

  1. Call the IDL Extractor for Natural, select the Natural server EMPLOYEE, check Redesign the interfaces and press Next.

    graphics/natExtractor_examples_userMap-1.png

  2. Model the extracted interface to suit your needs by creating a function getListOfEmployees.

    1. Mark the parameter OPERATION in the Natural Subprogram Source view or the Natural Parameters pane

    2. Set Constant 'L' for the parameter OPERATION.

    In the Natural Parameters pane, constant [L] is shown in brackets after the Natural parameter. OPERATION is removed from the IDL Parameters pane.

    At runtime, EntireX passes L as the value for the OPERATION parameter. This forces the EMPLOYEE LIST function to be executed.

    graphics/natExtractor_examples_userMap-2.png

  3. Suppress the Natural group EMPLOYEE, which is unused in the LIST function. This removes the IDL group EMPLOYEE from the IDL Parameters pane. The Natural parameter EMPLOYEE remains. Parameters that are suppressed in the IDL Parameters pane are displayed in italic font in the Natural Parameters pane.

    graphics/natExtractor_examples_userMap-3.png

    Note:
    Parameters set to constant are also displayed in italic font, because Set Constant suppresses them in the IDL Parameters pane too (see Step 2).

  4. Specify a readable name getListOfEmployees for the IDL Parameters, using the toolbar button graphics/icon_rename.png. The new name appears on the tab.

    graphics/natExtractor_examples_userMap-4.png

  5. Create a getListOfEmployees function for the DETAILS operation. A new interface is needed for this. Use the toolbar button graphics/icon_add.png and open a new tab. The IDL parameters are reset to defaults. The previously extracted getListOfEmployees interface still exists in the first tab. Once you reactivate the first tab, you will see the interface of getListOfEmployees again.

    graphics/natExtractor_examples_userMap-5.png

  6. Specify a readable name getDetailsOfEmployee for the IDL Parameters, using the toolbar button graphics/icon_rename.png. The name is displayed on the tab.

    graphics/natExtractor_examples_userMap-6.png

  7. Set constant 'D' for Natural parameter OPERATION to execute the EMPLOYEE DETAILS operation at runtime. The IDL parameter OPERATION is removed from the IDL Parameters pane and displayed in the Natural Parameters pane. The italic font indicates suppression.

    graphics/natExtractor_examples_userMap-7.png

  8. Suppress the Natural X-array EMPLOYEES, which is not needed in the DETAILS interface. The IDL parameter EMPLOYEES is removed from the IDL Parameters pane and displayed in italic font in the Natural Parameters pane.

    graphics/natExtractor_examples_userMap-8.png

  9. By default, the Natural parameter DETAILS is mapped. In this case, the redefinition of DETAILS in the Natural Subprogram Source pane contains information of more value.

    graphics/natExtractor_examples_userMap-9.png

  10. You can map the redefinition of DETAILS in the Natural Subprogram pane if you prefer to use this rather than the DETAILS parameter. Select REDEFINE DETAILS in the Natural Subprogram pane and press Map to Out. The IDL parameter DETAILS is turned into a group containing parameters that match the Natural redefinition.

    graphics/natExtractor_examples_userMap-10.png

  11. Press Finish to retrieve the extraction result in the form of a Software AG IDL file. At the same time, a Server Mapping Files for Natural (Workbench file with extension .cvm) is created. The Software AG IDL File describes the interfaces from the , while the server mapping file 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.

    graphics/natExtractor_examples_userMap-11.png

    To summarize: We created two IDL interfaces. In the IDL file, these resulted in two IDL programs: getListOfEmployees and getDetailsOfEmployee. Both IDL programs were given readable names (Steps 4 and 6). Meaningful fields were kept, while superfluous fields were suppressed (Steps 3 and 8). The program getDetailsOfEmployee contains the redefined fields of parameter DETAILS (see below) mapped during extraction (step 9).

    Note:
    The Natural server and the redesigned interfaces no longer match. The RPC client generated with the extracted interface 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.

    graphics/natExtractor_examples_userMap-12.png

Testing the Extraction Results

The following pictures use the extraction results described under Extracting a Natural Server - Modern Method with User-defined Mapping.

Start of instruction setTo test the extraction results (optional)

  1. You can test the results of the extraction operation and the Natural Server back end, using the EntireX IDL Tester. From the context menu of the IDL file in the EntireX Workbench, choose Software AG IDL Tester.

    graphics/natExtractor_examples_userMap-13.png

  2. Select getDetailsOfEmployee.

    graphics/natExtractor_examples_userMap-14.png

    Note that the Broker and Server parameters contain the explicit route to call the server program, and you can optionally ping the connection from this client. See EntireX IDL Tester in the EntireX Workbench documentation.

  3. Check the Integration Server log, the EntireX Adapter log or the RPC logs. Applies to all connection methods.

Task 2: Generate the Connection and Adapter Services in Integration Server

This section describes your first steps to create a new Integration Server connection. This is described in more detail under Using the Integration Server Wrapper, for example working with existing Integration Server connections. This section covers the following topics:

Step 1: Start the Integration Server Wrapper Wizard

Start of instruction setTo start the Integration Server Wrapper wizard

  1. In the context menu of a Software AG IDL file, choose Integration Server > Generate webMethods IS Connection.

    This starts the wizard with a list of existing Integration Server Wrapper connections.

    Note:
    If the selected IDL file is not valid because of a syntax error, an error dialog comes up and the wizard does not start.

  2. Continue with Step 2: Create a New Integration Server Connection.

Step 2: Create a New Integration Server Connection

graphics/using_createNew.png

Start of instruction setTo create a new Integration Server connection

  1. Define the new Integration Server connection on the wizard page.

    Notes:

    1. The only required field is Server. Enter the hostname of the Integration Server including an optional port number. If no port number is specified, port number defaults to "5555". The Integration Server Authentication can be passed with the User and Password fields.
    2. Optional settings are for secure connections. The Truststore for HTTPS contains all signed certificates and must be a valid truststore.
    3. The check box Verify host name checks that the hostname is entered in the stored certificate.
    4. When the Integration Server has Client Authentication enabled, you can specify your Keystore file and keystore Password.
    5. For managing Integration Server connections, see Integration Server Preferences in the Integration Server Wrapper documentation.
  2. Choose Next and continue with Step 3: Select the Connection Type.

Step 3: Select the Connection Type

graphics/using_connectionType.png

Start of instruction setTo create a new connection

  1. Select a connection type from the drop down list. Connection types are described under EntireX Adapter Connections in the EntireX Adapter documentation and Introduction to the Integration Server Wrapper.

    Note:
    The list of connection types is filtered: connection types that require a license are only shown if a corresponding license file is available. Reliable RPC connections are only shown if all IDL programs contain only IN parameters. Also, if a server mapping file is available, only those connection types that support the interface type specified in the server mapping file are shown.

  2. Click Next and continue with Step 4: Define Adapter Services for an RPC Connection.

Step 4: Define Adapter Services for an RPC Connection

graphics/using_define-rpc.png

Start of instruction setTo create a connection and related adapter services

  1. Select a package for the created objects.

  2. Define a folder name. If the folder does not exist, it will be created.

  3. Define a connection name.

  4. Define the parameters of the connection type. For details, see the EntireX and your webMethods Integration Server Applications.

    As a result, the folder will contain the connection and the adapter services (one for each IDL program). The name of a service is the same as the respective IDL program.

The default settings for new RPC adapter services are:

  • the Default package; if not available, the first package

  • the IDL library name for the Folder Name

  • the IDL library name with the suffix "Connection" for the Connection Name

Note:
When creating a connection, a package dependency is added such that the selected package depends on webMethods EntireX (the package WmEntireX) with the version currently used.

Task 3: Execute the Call from Integration Server to Natural

From the Service Development perspective, refresh the package where the connection service was written, select the adapter service and use the service test to Run Service. This invokes the adapter service through the connector service.

The following screenshots use the extraction results described in Extracting a Natural Server - Modern Method with User-defined Mapping.

We no longer have to specify operation codes to run the services. On output of the getDetailsOfEmployee service (see second screen below), the redefinition of the DETAILS group is directly available.

graphics/nat2is_test-1.png

You can use the generated EntireX adapter service like any other IS service - there is no difference. As the webMethods Integration Server 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:*) is mapped to Integration Server document list of getDetailsOfEmployee service.

In case of error or unexpected results:

  • Check the Integration Server log, the EntireX Adapter log or the RPC logs.

  • Use the IDL Tester as described under Testing the Extraction Results above.