Calling Integration Server from Natural

Scenario: "I have an Integration Server service and want to call this from a Natural application."

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

graphics/is2nat-simple.png

This document covers the following topics:

See also Common Integration Scenarios for other common user scenarios that can be handled by EntireX.


Introduction

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

graphics/intro.png

graphics/blue_1.gif Read package from Integration Server and generate Integration Server connection and listeners. See Using the IDL Extractor for Integration Server.
graphics/blue_2.gif Generate client interface objects for Natural client application and Natural test programs. See Natural Wrapper.
graphics/blue_3.gif Execute call from Natural client to Integration Server listener. See Sample Generation Result for the Client Side.

This scenario makes the following important assumptions:

For Task 1:

  • You have an Integration Server with the EntireX Adapter installed.

For Task 2:

  • You have a Natural RPC Server installed. Generating Natural code requires a running Natural RPC Server and either EntireX Broker or Integration Server.

    graphics/intro-assume2.png

    See your Natural documentation for setting up the Natural RPC Server.

For Task 3:

  • You have an Integration Server with the EntireX Adapter installed.

  • You can call the Integration Server service at runtime using different methods:

    • EntireX RPC
      For the EntireX RPC connection method you need EntireX Broker on one of the supported platforms: z/OS | UNIX | Windows | BS2000 | z/VSE.

      graphics/intro-assume3a.png

    • EntireX Direct RPC
      For the EntireX Direct RPC connection method there are no additional prerequisites. See also Direct RPC.

      graphics/intro-assume3b.png

Task 1: Generate Integration Server Connections and Listeners

Introduction

Follow the instructions for extracting a webMethods Integration Server (IS) service under Using the IDL Extractor for Integration Server.

This process creates the following EntireX metafiles:

  • an IDL file, containing definitions of the interface between client and server; see Software AG IDL File in the IDL Editor documentation

  • a webMethods IS Connection

  • a webMethods IS Listener, depending on connection type. See Listeners in the EntireX Adapter documentation.

Connection types are described under Creating Listener Objects in Integration Server.

Sample webMethods IS Service

Imagine that a new order management system is being developed with webMethods Integration Server in your organization. A package OrderManagement with flow service is provided. From your existing Natural application you would like to call the flow service placeOrder on the IS.

graphics/generate-server_sample.png

The following input is required:

  • ID of the item to be ordered (OrderItemID)

  • a quantity (OrderQuantity)

  • customer ID OrderCustomerID)

The following output is returned:

  • item name (OrderItemName)

  • unit and total price (OrderUnitPrice and OrderTotal)

  • etc.

Extracting the Interface of the webMethods IS Service

First create a project in Designer. This project is the container into which all extracted and generated EntireX artifacts are placed. Name this project Natural placeOrder client.

Start of instruction setTo start the IDL Extractor for Integration Server

  1. Switch to the EntireX perspective.

  2. Invoke the IDL Extractor for webMethods IS, which is a New Wizard in Eclipse. From the File menu, choose New. Select IDL Extractor for webMethods IS in the following page.

    Or:
    Choose New from the toolbar or context menu of a view showing resources.

    Or:
    Press Ctrl-N to start the selection of the New Wizards.

  3. If you are using the wizard for the first time without any predefined Integration Server connections, enter the TCP/IP address of the webMethods IS to extract from. Otherwise select the connection to the Integration Server.

  4. Press Next.

Start of instruction setTo extract the IDL from the selected package

  1. Under Source (Integration Server), select the package you want to extract from.

    graphics/common_generate-server_extract.png

  2. For Target (Eclipse Workspace), specify project Natural placeOrder client. Extraction results will be placed in this container. You can keep the IDL File Name as it has been derived from the package name by default. Since Natural is your desired endpoint, select Optimize extracted IDL for usage with: Natural.

    With Map Integration Server data type to IDL you define the default for webMethods IS variable length types with no specified constraints. For historical reasons, you can map them to two types of string:

    • Natural variable-length strings, so-called Natural DYNAMIC variables

    • classic Natural fixed-length strings

    You can see the effect of this default under Viewing the Extracted IDL.

  3. A listener is required for calling webMethods IS from an RPC client, so check Create Listener Objects in Integration Server.

  4. Press Next.

Creating Listener Objects in Integration Server

Start of instruction setTo create Listener Objects in Integration Server

  1. Select a Listener connection type used for inbound connection to the Integration Server.

    • An EntireX RPC Listener connection is the standard way and is always available.

    • If your interface contains only In parameters, an EntireX Reliable RPC Listener connection is available.

    • If it is enabled by the license for the webMethods Integration Server:

      • an EntireX Direct RPC Listener connection is available

      • if your interfaces contain only In parameters, an EntireX Direct Reliable RPC Listener connection is available

    graphics/common_generate-server_listener.png

  2. On this page, you set the properties for the listener objects to create; these objects will wait for the incoming Natural requests. Select the package and specify the folder name into which the listener is generated. If the folder does not exist, it will be created automatically.

  3. Keep the defaults given for RPC Listener Connection to EntireX. The Broker ID is a TCP/IP or SSL/TLS address and Server Address is an EntireX-specific namespace to locate a target server (here: OrderManagementListener).

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

  5. Press Finish. The listener and the connection appear in the package navigator. For the package navigator, switch to the service development perspective by choosing Window > Perspective > Open Perspective > Service Development.

Viewing the Extracted IDL

Start of instruction setTo view the extracted the IDL

  • The Software AG IDL is saved in the target Eclipse workspace as selected: container Natural placeOrder client and IDL file OrderManagement.idl:

    graphics/common_generate-server_view.png

The IDL file is the central artifact from which Natural code is generated later in Task 2: Generate Client Interface Objects and Build Client Application. Extracted Software IDL data and resulting Natural types in the generated client interface objects depend on constraints and on the extraction settings under Map Integration Server data type to IDL, option alphanumeric with variable length and alphanumeric with fixed length. See Extracting the Interface of the webMethods IS Service.

It is best if the Natural types match your data. This means:

  • Numeric data should be mapped to numeric Natural types of the appropriate range. In our example this is the case for OrderItemID, OrderQuantity and OrderCustomerID.

  • For string data where the length is known, set a length constraint too. This is the case for OrderUnitPrice, OrderTotal, ZipCode and CountryCode. For fixed-length short fields (1-4 bytes) this shortens the message length and improves performance.

  • We recommend you set the option alphanumeric with variable length (see Extracting the Interface of the webMethods IS Service) as the default for string data where the length is unknown and no length constraint could be set as for IS parameter OrderShippingDate and OrderConfirmationFlag. This results in IDL type AV (see above, left IDL example) and - last but not least - in Natural type A DYNAMIC in the generated client interface objects. See Task 2: Generate Client Interface Objects and Build Client Application. You have more freedom and no limitations on the length of the string being transferred.

The option alphanumeric with fixed length is there for historical reasons. It results in a classic fixed-length Natural type A with length for IS string parameter without constraints, in our example A256 as Natural and IDL data type (see IDL example on the right above). This limits the maximum transferred length to 256 characters.

For more information on data type mapping, see Mapping Integration Server Data Types to IDL in the IDL Extractor for Integration Server documentation.

Testing the Extraction Results (Optional)

You can test the results of the extraction and the server back end, using the EntireX IDL Tester.

Start of instruction setTo test the extraction results

  1. For EntireX RPC (see Task 3 in the Introduction) and an RPC Listner Connection, make sure EntireX Broker is running.

  2. Enable the EntireX Adapter Listener.

    graphics/common_generate-server_test.png

  3. Activate the EntireX perspective by choosing Window > Perspective > Open Perspective > EntireX, and from the context menu of the IDL file, choose IDL Tester.

  4. This step depends on the method used to call the server (see Task 3 in the Introduction).

    • For EntireX RPC, enter the same TCP/IP address for Broker that you supplied when you created the RPC Listener Connection to EntireX (localhost:1971).

    • For Direct RPC, that is, you generated a Direct RPC Listener Connection, enter the TCP/IP address from the Integration Server (localhost:1971).

  5. For Server, enter the values you specified for the server address (RPC/SRV1/CALLNAT).

    graphics/common_generate-server_test-2.png

Task 2: Generate Client Interface Objects and Build Client Application

Start of instruction setTo generate client interface objects and build a client application

  • For Natural code generation, make sure the EntireX Perspective is active: Choose Window > Perspective > Open Perspective > EntireX. From context menu of the IDL file, choose Natural > Generate RPC Client.

    graphics/generate-client.png

    In the Natural Wrapper you can specify the names of the generated Natural files to match your naming conventions (see picture above). Three Natural files are generated:

    • A client subprogram (extension .NSN). Also named CALLNAT. In EntireX terminology this acts as the client interface object.

    • A client PDA (extension .PDA). This contains the data description of the API.

    • A test program (extension .NSP). This calls the client interface object. Generation of test programs can be switched off.

    Natural developers often use use a single character on a fixed position in the 8-character Natural name to represent the object type of the Natural object (typically P=program; N=subprogram; A=PDA). The last character of the names from our example above uses this convention.

    The test program can also be used as an example of how to code an RPC client in Natural. It uses the Natural API RPC-CNTX. Parameters such as host, port, server address, user ID etc. can be set for RPC communication. Especially for a quick test, this is the simplest way to set the connection parameters. See your Natural documentation for more information on API RPC-CNTX. You can also set connection parameters using a service directory. See Service Directory Maintenance in the Natural SYSRPC Utility documentation for more information.

Task 3: Execute the Call from Natural to Integration Server

The following alternatives are provided for testing:

Generated Test Program

Use the generated test program to execute the call.

Start of instruction setTo use the generated test program

  1. For EntireX RPC (see Task 3 in the Introduction) and an RPC Listner Connection, make sure EntireX Broker is running.

  2. Enable the EntireX Adapter Listener.

    graphics/common_generate-server_test.png

  3. This step depends on the method used to call the server (see Task 3 in the Introduction).

    • For EntireX RPC, enter the same TCP/IP address for Broker that you supplied when you created the RPC Listener Connection to EntireX (localhost:1971).

    • For Direct RPC, that is, you generated a Direct RPC Listener Connection, enter the TCP/IP address from the Integration Server (localhost:1971).

  4. Set the field Server name to match the middle part of the Server address specified under Creating Listener Objects in Integration Server. Example: If you specify SRV1 in the test program, RPC/SRV1/CALLNAT will be used.

    graphics/execute_generate.png

IDL Tester

Use the EntireX IDL Tester to execute the call.

Start of instruction setTo test the extraction results

  1. For EntireX RPC (see Task 3 in the Introduction) and an RPC Listner Connection, make sure EntireX Broker is running.

  2. Enable the EntireX Adapter Listener.

    graphics/common_generate-server_test.png

  3. Activate the EntireX perspective by choosing Window > Perspective > Open Perspective > EntireX, and from the context menu of the IDL file, choose IDL Tester.

  4. This step depends on the method used to call the server (see Task 3 in the Introduction).

    • For EntireX RPC, enter the same TCP/IP address for Broker that you supplied when you created the RPC Listener Connection to EntireX (localhost:1971).

    • For Direct RPC, that is, you generated a Direct RPC Listener Connection, enter the TCP/IP address from the Integration Server (localhost:1971).

  5. For Server, enter the values you specified for the server address (RPC/SRV1/CALLNAT).

    graphics/common_generate-server_test-2.png